Documentation
¶
Overview ¶
Package intake runs a team's task intake adapter (hadron-cli#1961, cor:agt:120:04): a local executable that knows a tracker, which the CLI calls to list the outside items nobody tracks yet, and to mark the ones it claims. Hadron makes no tracker call (cor:agt:120, D2); the adapter holds the team's own tracker credential, never Hadron's.
The contract's calls and what they carry are the spec's. HOW a call is invoked is the CLI owner's to decide (cor:agt:120:04), and is decided here:
<adapter> <call> e.g. `hadron-task-adapter-github list-untracked`
One argument, the call's name, never a shell string. The request is ONE JSON object on stdin (it always carries "contractVersion"); the answer is ONE JSON object on stdout and exit 0. Any other exit is a refusal by the adapter. The adapter's text is untrusted terminal data: it is size-capped, parsed strictly, never executed, and printed terminal-safe by the caller.
Index ¶
- Constants
- Variables
- func CursorKey(server, appRef, adapter string) string
- type BusyError
- type CursorStore
- type Describe
- type Item
- type OutputError
- type Page
- type RefusedError
- type Runner
- func (r *Runner) Describe(ctx context.Context) (Describe, error)
- func (r *Runner) ListUntracked(ctx context.Context, cursor, forWorker string, limit int) (Page, error)
- func (r *Runner) MarkTracked(ctx context.Context, externalID string, task Task, worker Worker) error
- func (r *Runner) Report(ctx context.Context, externalID string, task Task, state string) error
- func (r *Runner) Untrack(ctx context.Context, externalID string) error
- func (r *Runner) Walk(ctx context.Context, forWorker string, limit int, ...) error
- type SkewError
- type Task
- type Worker
Constants ¶
const ( MaxOutputBytes = 1 << 20 // stdout of one call MaxStderrBytes = 4096 // kept for the refusal message only MaxItemsPerPage = 100 MaxPages = 50 ServerExternalIDMax = 512 // the server's externalId cap, counted in code points (references.ts: for..of) MaxExternalIDLen = 2048 // the server's own cap is 512; this only bounds memory MaxCursorLen = 4096 MaxTextLen = 1024 // adapter-supplied display text: name, title DefaultTimeout = 60 * time.Second )
Bounds on what an adapter may hand back. A hostile or broken adapter hits one of these and the call is refused; nothing is truncated into a plausible answer.
const ContractVersion = 1
ContractVersion is the one contract version this CLI speaks. An adapter that describes another is refused with a SkewError, never guessed at.
Variables ¶
var FeedLockWait = 2 * time.Minute
FeedLockWait is how long a second run waits for the first to finish with a feed before it gives up as busy.
Functions ¶
Types ¶
type CursorStore ¶
type CursorStore struct {
// Path is the JSON file; its directory must exist or be creatable.
Path string
}
CursorStore keeps, per server, App and adapter, the server's OPAQUE cursor for the reconcile pass (cli#1962): where the CLI last read the App's "tasks with an external id changed" feed. It is the server's value, never a client clock (cor:agt:120, minimal write-back). A file beside the CLI's config, written atomically under the config lock so parallel runs do not lose each other's updates.
func DefaultCursorStore ¶
func DefaultCursorStore() (*CursorStore, error)
DefaultCursorStore is the store beside the CLI's config.
func (*CursorStore) Get ¶
func (s *CursorStore) Get(key string) (string, error)
Get returns the stored cursor, or "" when the feed was never read.
func (*CursorStore) Serialize ¶
Serialize runs fn holding an exclusive per-feed lock, so two runs on one feed (a ticker and a hand run) never overlap: the adapter's effects and the cursor write of one finish before the other reads the cursor (cli#1975). A run that cannot get the lock within FeedLockWait fails with *BusyError; the context ends the wait early. The OS drops the lock if the process dies.
func (*CursorStore) Set ¶
func (s *CursorStore) Set(key, cursor string) error
Set stores cursor for key.
type Describe ¶
type Describe struct {
Name string `json:"name"`
ContractVersion int `json:"contractVersion"`
Calls []string `json:"calls"`
Filters []string `json:"filters"`
Order string `json:"order"`
}
Describe is what `describe` answers.
type Item ¶
type Item struct {
// ExternalID is the item's canonical URL exactly as the adapter wrote it:
// compared exactly by the server, so the CLI never normalises it
// (cor:agt:120:02; `normalize` is the adapter's optional call).
ExternalID string `json:"externalId"`
Title string `json:"title"`
}
Item is one outside item the adapter says is not yet tracked.
type OutputError ¶
OutputError is an adapter answer the CLI will not use: oversized, not one JSON object, a field out of bounds, a cursor that loops.
func (*OutputError) Error ¶
func (e *OutputError) Error() string
type RefusedError ¶
RefusedError is an adapter that ran and exited non-zero (or could not run).
func (*RefusedError) Error ¶
func (e *RefusedError) Error() string
type Runner ¶
type Runner struct {
// Path is the executable: a path, or a bare name looked up on PATH. It is
// run directly, never through a shell, and gets no arguments but the call.
Path string
Timeout time.Duration
}
Runner calls one adapter executable.
func (*Runner) Describe ¶
Describe asks what the adapter is and checks the contract version. It is the first call of every run, so a skewed adapter is refused before it is asked for anything else.
func (*Runner) ListUntracked ¶
func (r *Runner) ListUntracked(ctx context.Context, cursor, forWorker string, limit int) (Page, error)
ListUntracked asks for one page. cursor is the opaque value the previous page returned, "" for the first: the CLI never builds or offsets one (cor:agt:120:04). forWorker is `--for X`, passed as written.
func (*Runner) MarkTracked ¶
func (r *Runner) MarkTracked(ctx context.Context, externalID string, task Task, worker Worker) error
MarkTracked tells the adapter an item is tracked, after the CLI's create claimed it (cor:agt:120:04). The task's portal URL is the server's, passed as printed; the CLI builds none.
func (*Runner) Report ¶
Report tells an adapter that declares `report` that a task ended in state (cor:agt:120, D4: a cancel may call it; the adapter's choice what to do).
func (*Runner) Untrack ¶
Untrack tells the adapter an item was released: its task no longer holds it (cli#1962, cor:agt:120:04). It is given the RELEASED id the server reported, since the task holds none.
func (*Runner) Walk ¶
func (r *Runner) Walk(ctx context.Context, forWorker string, limit int, yield func(Page) (stop bool, err error)) error
Walk pages list-untracked by its opaque cursor until the adapter says there is no more, yield asks to stop, or a bound is hit. A cursor the adapter has already given (or an empty page that keeps promising more) is a loop and is refused; so is a list longer than MaxPages. Items seen on an earlier page are not offered to yield again.
type SkewError ¶
type SkewError struct{ Got int }
SkewError is a contract-version mismatch. The command maps it to its own exit code.
type Task ¶
type Task struct {
ID string `json:"id"`
Handle string `json:"handle,omitempty"`
PortalURL string `json:"portalUrl,omitempty"`
}
Task and Worker are what `mark-tracked` is given (cor:agt:120:04). Empty fields are omitted: the portal URL is the server's or nothing, and a worker detail the CLI does not know is left out rather than invented.