intake

package
v0.46.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 16 Imported by: 0

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

View Source
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.

View Source
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

View Source
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

func CursorKey

func CursorKey(server, appRef, adapter string) string

CursorKey names one feed: the server, the App and the adapter. The adapter is part of the key so two adapters in one App each see every change.

Types

type BusyError

type BusyError struct{ Waited time.Duration }

BusyError is a feed another run is still reconciling.

func (*BusyError) Error

func (e *BusyError) Error() string

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

func (s *CursorStore) Serialize(ctx context.Context, key string, fn func() error) error

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.

func (Describe) Has

func (d Describe) Has(call string) bool

Has reports whether the adapter says it answers call. Calls lists every call the adapter answers, the core ones included (this CLI's invocation format).

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

type OutputError struct {
	Call   string
	Reason string
}

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 Page

type Page struct {
	Items      []Item
	NextCursor string // "" when the list is exhausted
}

Page is one validated page of `list-untracked`.

type RefusedError

type RefusedError struct {
	Call   string
	Detail string // already terminal-safe
}

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

func (r *Runner) Describe(ctx context.Context) (Describe, error)

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

func (r *Runner) Report(ctx context.Context, externalID string, task Task, state string) error

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

func (r *Runner) Untrack(ctx context.Context, externalID string) error

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.

func (*SkewError) Error

func (e *SkewError) Error() string

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.

type Worker

type Worker struct {
	ID    string `json:"id,omitempty"`
	Name  string `json:"name,omitempty"`
	Role  string `json:"role,omitempty"`
	Model string `json:"model,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL