Documentation
¶
Overview ¶
Package capdecl is the declaration of what a stack can do for a run: a named capability, what a caller reads about it, and the input it takes. A program a run grant covers calls a capability by name (`cap://<name>`, chassis/server/capgw); the run's `_grant` stack decides the call; the stack that DECLARES the name runs it, from its start (or from the scope the declaration names).
A stack declares a capability as one small YAML file under the reserved CAPS/ subtree, beside SANDBOXES/ and OUTLETS/:
OPS/<stack>/CAPS/<name>.yaml
The file deploys with `txco apply` as a stack_files row (inline on a single node, fingerprint + CAS on the fleet — the SANDBOXES/ treatment) and is validated at apply. A SANDBOXES/ declaration says what a run MAY call; a CAPS/ declaration says who answers. A tenant's catalogue is the declarations of its active stacks: `txco://caps/list`, `txco caps list`.
This file is the leaf layer: the reserved-path vocabulary, with no dependency on stores, so the CLI, the admin producer and the control-event applier can import it cheaply.
Index ¶
Constants ¶
const ( // MaxInputs bounds the inputs one capability names. MaxInputs = 32 // MaxDescription bounds the capability's description: it is what a // model reads to decide whether to call, so it is longer than a note. MaxDescription = 2048 // MaxInputDescription bounds one input's description. MaxInputDescription = 512 // MaxTimeout bounds the declared timeout, in milliseconds. The inlet's // own ceiling still applies; a declaration can only shorten the wait. MaxTimeout = 3600000 )
Ceilings on one declaration.
const ( Dir = "CAPS" DeclExt = ".yaml" )
Reserved top-level directory and the declaration extension.
Variables ¶
var ErrNotDeclared = errors.New("cap: not declared")
ErrNotDeclared: no active stack of the tenant has a CAPS/<name>.yaml.
Functions ¶
func CheckEntry ¶
CheckEntry reports whether the declaration's entry names a scope the stack has. scopes is the set of scope numbers of the declaring stack. No entry is the stack's start, which any stack with a scope has.
func Name ¶
Name returns the capability a declaration path belongs to: "CAPS/local.web.fetch.yaml" → "local.web.fetch". It returns "" when the path is not under CAPS/, is nested, has the wrong extension, or names an invalid capability — the same shape validateStackFilePath enforces at upload. A capability name holds dots, so the extension is trimmed off the end rather than cut at the first dot.
Types ¶
type Decl ¶
type Decl struct {
Description string `yaml:"description"`
Entry int `yaml:"entry"`
Input map[string]InputField `yaml:"input"`
Timeout int `yaml:"timeout"`
}
Decl is one CAPS/<name>.yaml: who answers a capability and what it takes. The file's existence is the declaration — the stack that holds it answers the capability — and every key is optional. Only what the chassis reads is declared here; a key it does not read is a deploy error, not a promise.
description: Send a message by email. # what a caller reads
input: # what the call carries
to:
description: the recipient's address
required: true
subject: {}
timeout: 60000 # ms; shortens the wait
entry: 7000 # see below
A call ENTERS THE STACK AT ITS START, `<stack>/0`, like every other inlet's run (`_cron/0`, `_mail/0`): the stack's scopes run in order and their WHENs pick the call up (`@src == "cap"`, `@cap.name`). `entry` is for a stack that does other work too and wants a capability's run to begin further in: it names the scope of THIS stack the run starts from.
Parsed strictly: an unknown key is a deploy error, not a silent ignore.
func (*Decl) Stage ¶
Stage is where a call enters: "<stack>/<entry>", the shape a stage jump takes (processor.StagePartsRE) — "<stack>/0", the stack's start, when no entry is declared.
func (*Decl) TimeoutDuration ¶
TimeoutDuration is the declared timeout; zero means the inlet's ceiling.
type InputField ¶
type InputField struct {
Description string `yaml:"description" json:"description,omitempty"`
Required bool `yaml:"required" json:"required,omitempty"`
}
InputField is one input a capability takes.
Source Files