mirror of
https://github.com/larksuite/cli.git
synced 2026-07-09 10:29:48 +08:00
461e3c62c9
Introduces extension/platform — the in-process plugin SDK external
Go forks of lark-cli use to extend or restrict the command surface.
Plugins compile in via blank import; there is no dynamic loading
and no RPC isolation.
Public SDK (extension/platform):
- Plugin interface (Name / Version / Capabilities / Install).
- Registrar verbs: Observe, Wrap, On, Restrict.
- Hook types: Observer (side-effect, panic-safe, fires Before/After
RunE), Wrapper (middleware, may short-circuit via AbortError),
LifecycleHandler (Startup / Shutdown), Selector with nil-safe
And/Or/Not composition.
- Risk / Identity are defined string types with closed taxonomies;
ParseRisk / ParseIdentity convert raw strings with the
absent-vs-invalid distinction the engine relies on.
- Builder ergonomic constructor (NewPlugin().Observer().Wrap()
...MustBuild()) that enforces name/hookName grammar, hookName
uniqueness, and the Restrict ↔ FailClosed pairing regardless of
call order.
- Invocation is a read-only interface; the framework's concrete
invocation type lives in internal/hook so plugins cannot
fabricate denial / strict-mode / identity state. Args() returns
a defensive copy on every call so hook mutation cannot leak
into the original RunE.
- CommandDeniedError + AbortError carry structured fields for the
closed `command_denied` / `hook` envelope contract.
- ResetForTesting gated behind //go:build testing.
- README + godoc examples (Observer / Wrapper / Restrict) + two
runnable example forks (audit-observer, readonly-policy).
Host (internal/platform, internal/hook, internal/cmdpolicy):
- InstallAll: staged plugin registration with atomic commit, panic
isolation, FailOpen / FailClosed semantics, RequiredCLIVersion
semver check, single-Restrict invariant, duplicate-plugin-name
detection.
- hook.Install wraps every runnable cmd.RunE with:
Before observers (panic-safe) → denial guard → composed Wrap
chain → original RunE → After observers (always fire, even on
err). Denied commands physically bypass the Wrap chain so a
plugin Wrapper cannot suppress or rewrite a denial; observers
still see the attempt for audit.
- Recover shim around plugin Wrappers converts panics (including
the factory call) into a structured `hook` envelope with
reason_code=panic; namespacing shim attributes AbortError to
the namespaced hook name.
- cmdpolicy (renamed from internal/pruning) is the user-layer
command policy engine: walks the cobra tree, evaluates each
runnable command against a Rule's four-axis filter (Allow /
Deny / MaxRisk / Identities), produces parent-group aggregate
denials, and installs denyStubs. Rule.AllowUnannotated opts out
of the unannotated-deny gate for gradual adoption; risk_invalid
typos always deny with an edit-distance "did you mean"
suggestion.
- Strict-mode stub in cmd/prune.go composes the shared
detail.* / wrapped CommandDeniedError shape via cmdpolicy
helpers (BuildDenialError / CommandDeniedFromDenial /
DenialDetailMap), so command_denied envelopes from strict-mode
and user-layer policy carry the same closed-enum fields
(detail.layer / reason_code / policy_source). The historical
short Message + independent Hint are preserved unchanged.
- cmdpolicy/yaml: structural parsing of ~/.lark-cli/policy.yml
with KnownFields strict mode, including allow_unannotated.
- `config policy show` / `config policy validate` and the plugin
inventory diagnostic surface the resolved Rule (allow,
deny, max_risk, identities, allow_unannotated) and the hook
contributions per plugin.
Envelope contract (docs/extension/reason-codes.md):
- error.type is a closed set: command_denied, hook, plugin_install,
plugin_conflict, plugin_lifecycle.
- reason_code is a closed enum per error.type, dispatched on by
external agents and CI integrations.
- detail.layer = "policy" | "strict_mode" attributes the rejection.
Build / CI:
- Makefile unit-test / vet / coverage and ci.yml fast-gate +
unit-test + coverage now pass -tags testing so register_testing.go
is visible; ./extension/... is in the package list so the SDK's
own tests actually run.
- fmt-check and examples-build Makefile targets.
- bmatcuk/doublestar/v4 added as a direct dependency for `**` glob
matching in Rule.Allow / Rule.Deny.
Author-facing material:
- docs/extension/ (quickstart, plugin-author-guide, reason-codes)
is provided in the working tree but kept out of git tracking
per repo convention (.gitignore covers docs/).
Change-Id: I3b8ecc2923bd54c2dff19e5dce8a0855a6f9e703
40 lines
1.9 KiB
Go
40 lines
1.9 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package platform
|
|
|
|
import "context"
|
|
|
|
// Handler is the inner function shape every Wrapper composes. It IS the
|
|
// "command business logic" from the Wrapper's perspective -- calling
|
|
// next(ctx, inv) inside a Wrapper means "let the command proceed";
|
|
// returning early without calling next short-circuits.
|
|
type Handler func(ctx context.Context, inv Invocation) error
|
|
|
|
// Observer is a side-effect-only command hook. No return value, no
|
|
// next-chain control: an Observer can read Invocation but cannot prevent
|
|
// the command from running. Used for audit, metrics, and completion
|
|
// logs. After-stage Observers fire even when the command failed
|
|
// (Invocation.Err() is populated in that case).
|
|
type Observer func(ctx context.Context, inv Invocation)
|
|
|
|
// Wrapper is a middleware-style hook: it receives the rest of the
|
|
// handler chain and returns a wrapped version. The Wrapper decides
|
|
// whether to call next (allow), abstain (deny, return an AbortError),
|
|
// or transform the result. Multiple Wrappers compose left-to-right by
|
|
// registration order; the outermost runs first.
|
|
//
|
|
// ⚠️ IMPORTANT: The factory function `func(next Handler) Handler` is
|
|
// invoked ONCE PER COMMAND DISPATCH, not once at plugin install. This
|
|
// lets the framework recover from a panicking factory and convert it
|
|
// to a structured envelope, but it means any state captured by the
|
|
// outer closure is rebuilt on every command. Long-lived state (HTTP
|
|
// clients, caches, metrics counters) MUST live on the Plugin struct
|
|
// or in package-level variables, never in factory-local captures.
|
|
type Wrapper func(next Handler) Handler
|
|
|
|
// LifecycleHandler runs at one of the process-level LifecycleEvent
|
|
// slots. The handler may use ctx for cancellation; in the Shutdown
|
|
// case the framework supplies a context with a 2-second hard deadline.
|
|
type LifecycleHandler func(ctx context.Context, lc *LifecycleContext) error
|