Documentation
¶
Overview ¶
Package invoke is the process-wide invocation framework: services opt into the Invokable capability, and every instance exposes the shared default invocations (config, logs). The control channel is its gRPC surface.
Index ¶
- Constants
- func HasInvocations() bool
- func InvocationNames(target string) []string
- func InvokeStream(ctx context.Context, target, name string, args map[string]any, emit StreamEmit) error
- func IsDrained(id string) bool
- func IsStreaming(target, name string) bool
- func Redact(cfg map[string]any) map[string]any
- func RegisterInstance(id, service string, config map[string]any, inv Invokable, ...)
- func SetDrained(id string, out bool)
- type ArgSpec
- type Args
- type Builder
- func (b *Builder) Arg(name, description string) *Builder
- func (b *Builder) Dangerous() *Builder
- func (b *Builder) Handle(fn Handler)
- func (b *Builder) HandleStream(fn StreamHandlerFunc)
- func (b *Builder) Mutating() *Builder
- func (b *Builder) OptArg(name, description string) *Builder
- func (b *Builder) Stream() *Builder
- type Handler
- type InvocationKind
- type InvocationSpec
- type Invokable
- type Result
- type Set
- type StreamEmit
- type StreamHandlerFunc
- type StreamInvokable
Constants ¶
const ActivityInvocation = "activity"
ActivityInvocation is a built-in invocation every service instance exposes: it reports how many requests the instance's service is currently serving, how many it has served, and how long it has been idle — so an operator can tell when a (drained) instance has quiesced and is safe to restart.
const ConfigInvocation = "config"
ConfigInvocation is the built-in invocation every service instance exposes: it returns the instance's effective, redacted configuration.
const LogLevelInvocation = "loglevel"
LogLevelInvocation is a built-in invocation every service instance exposes: it reports, and optionally sets, the process's effective log level at runtime. The change is in-memory and process-wide; a restart reverts to the configured log level.
const LogsInvocation = "logs"
LogsInvocation is a built-in invocation every service instance exposes: the process's recent log lines, filtered to the instance's service. Invoke returns a snapshot, InvokeStream follows.
const MetaInvocations = "invocations"
MetaInvocations is the registry metadata key holding a node's invocation names (comma-separated), so catalogs can be answered without dialing.
const RedactedValue = "<redacted>"
RedactedValue is the placeholder substituted for a secret.
const RotationInvocation = "rotation"
RotationInvocation is a built-in invocation that takes an instance out of rotation (state=drain) or returns it (state=ready) at runtime. The change is in-memory and per node: a restart reverts it. The runtime's heartbeat advertises the resulting registry state, and the service selector excludes draining nodes, so a drained instance receives no new traffic while staying alive and control-reachable.
const StackInvocation = "stack"
StackInvocation is a built-in invocation every service instance exposes: a dump of the process's goroutine stacks with basic runtime stats — the first tool to reach for when a process hangs.
const VersionInvocation = "version"
VersionInvocation is a built-in invocation every service instance exposes: the binary's build information and the process uptime, so a mixed fleet's version drift is visible with one fan-out.
Variables ¶
This section is empty.
Functions ¶
func HasInvocations ¶
func HasInvocations() bool
HasInvocations reports whether this process exposes anything invokable; the runtime gates the control channel on it.
func InvocationNames ¶
InvocationNames returns just the names a target exposes, for the MetaInvocations registry metadata.
func InvokeStream ¶
func InvokeStream(ctx context.Context, target, name string, args map[string]any, emit StreamEmit) error
InvokeStream is the streaming counterpart of Invoke: built-in defaults are handled by the framework, anything else needs the target's StreamInvokable.
func IsStreaming ¶
IsStreaming reports whether the named invocation on a target is streaming.
func Redact ¶
Redact returns a deep copy of cfg with secret-looking values masked: keys matched by name, string values also checked for inline DSN credentials. The input is never modified.
func RegisterInstance ¶
func RegisterInstance(id, service string, config map[string]any, inv Invokable, counter *activity.Counter)
RegisterInstance records a service instance under its node id, with its config (redacted here), optional Invokable, and optional request counter.
func SetDrained ¶
SetDrained marks (out) or clears a node id as drained.
Types ¶
type Args ¶
Args are an invocation's arguments, with typed accessors over their string wire form. A missing key yields the zero value.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder configures one invocation: chain Arg/OptArg/Mutating/Dangerous and finish with Handle.
func (*Builder) HandleStream ¶
func (b *Builder) HandleStream(fn StreamHandlerFunc)
HandleStream sets the streaming implementation and marks the invocation streaming. An invocation may have both a Handle and a HandleStream.
type InvocationKind ¶
type InvocationKind string
InvocationKind classifies an invocation for audit and CLI-level gating.
const ( // KindReadonly returns a redacted, serializable snapshot and changes nothing. KindReadonly InvocationKind = "readonly" // KindMutating changes state in a bounded, expected way. KindMutating InvocationKind = "mutating" // KindDangerous changes state in a way that warrants extra confirmation. KindDangerous InvocationKind = "dangerous" )
type InvocationSpec ¶
type InvocationSpec struct {
Name string
Description string
Args []ArgSpec
Kind InvocationKind
// Streaming marks an invocation that emits a stream of results (via
// InvokeStream) rather than a single one (Invoke).
Streaming bool
}
InvocationSpec describes one invocation: its name, arguments and kind.
func Invocations ¶
func Invocations(target string) ([]InvocationSpec, bool)
Invocations returns the invocations a target exposes on this node: the shared defaults plus the target's own. ok is false for an unknown target.
type Invokable ¶
type Invokable interface {
// Invocations is the list of invokables exposed by the service, to help the CLI
// autocompletion. Actual Invoke() calls may be done with arbitrary `name` values.
Invocations() []InvocationSpec
// Invoke runs the named invocation with the given arguments. It is expected
// to be a router across all names returned by Invocations().
Invoke(ctx context.Context, name string, args map[string]any) (Result, error)
}
Invokable is the capability a service implements to expose operations to the Admin API. It is opt-in; a read is simply an invocation with KindReadonly.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is a service's collection of named invocations. It implements Invokable: a service embeds a *Set and declares its methods instead of hand-writing the catalog, routing and required-arg checks. Build it once at construction; it is read-only afterward.
func (*Set) Invocations ¶
func (s *Set) Invocations() []InvocationSpec
Invocations implements Invokable: the catalog, in registration order.
func (*Set) InvokeStream ¶
func (s *Set) InvokeStream(ctx context.Context, name string, args map[string]any, emit StreamEmit) error
InvokeStream implements StreamInvokable.
type StreamEmit ¶
StreamEmit delivers one result of a streaming invocation; it returns an error when the consumer is gone.
type StreamHandlerFunc ¶
type StreamHandlerFunc func(ctx context.Context, args Args, emit StreamEmit) error
StreamHandlerFunc runs one streaming invocation.
type StreamInvokable ¶
type StreamInvokable interface {
// InvokeStream runs the named streaming invocation, emitting each result
// until it completes, ctx is done, or emit reports the consumer gone.
InvokeStream(ctx context.Context, name string, args map[string]any, emit StreamEmit) error
}
StreamInvokable is the optional streaming counterpart of Invokable.
Source Files