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
- Variables
- func CheckEntry(d *Decl, scopes map[int]bool) error
- func CheckEntryAs(kind string, d *Decl, scopes map[int]bool) error
- func DeclPath(name string) string
- func IsCapPath(p string) bool
- func Missing(fields map[string]Field, doc string) []string
- func Name(p string) string
- func ValidInput(s string) bool
- type Decl
- type Field
- type InputField
Constants ¶
const ( // MaxInputs bounds the inputs one capability names; MaxOutputs the // outputs it promises. MaxInputs = 32 MaxOutputs = 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 or output'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 CheckEntryAs ¶ added in v0.2.48
CheckEntryAs is CheckEntry with the declaration named as the caller's.
func Missing ¶ added in v0.2.48
Missing is the sorted list of the required fields that doc, a JSON object, lacks: absent, or present as null. An empty list means doc has every field the declaration requires; it says nothing about their shape, which a declaration does not describe.
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.
func ValidInput ¶
ValidInput reports whether s may name an input or an output.
Types ¶
type Decl ¶
type Decl struct {
Description string `yaml:"description"`
Entry int `yaml:"entry"`
Input map[string]Field `yaml:"input"`
Output map[string]Field `yaml:"output"`
Timeout int `yaml:"timeout"`
}
Decl is one CAPS/<name>.yaml: who answers a capability, what it takes and what it answers. 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: {}
output: # what the answer carries
mid:
description: the message id
required: true
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.
The same shape declares an ENTRY a call may name (CALLS/<name>.yaml, chassis/calldecl): there `input` is checked before the callee runs and `output` after it ends. On a capability, `output` is checked the same way when the answer comes; `input` is what a caller reads, and the stack's own rules decide what a call without it gets.
Parsed strictly: an unknown key is a deploy error, not a silent ignore.
func ParseDeclAs ¶ added in v0.2.48
ParseDeclAs is ParseDecl with the declaration named as the caller's: a call entry's errors say "call declaration".
func (*Decl) Returns ¶ added in v0.2.48
Returns is the sorted list of the outputs the capability names.
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 Field ¶ added in v0.2.48
type Field struct {
Description string `yaml:"description" json:"description,omitempty"`
Required bool `yaml:"required" json:"required,omitempty"`
}
Field is one input a capability takes, or one output it answers with.
type InputField ¶
type InputField = Field
InputField is the name Field had when a declaration named inputs only.
Source Files