dispatch

package
v0.56.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package dispatch defines the Dispatcher interface for provisioning dispatch infrastructure during install. Implementations (e.g. GCF) create the cloud function, OIDC federation, and org-level secrets/variables needed by the shim workflow.

Index

Constants

View Source
const TransportLabelsLimit = 1024

TransportLabelsLimit is the byte bound the GitLab transport (internal/poll) applies to the JSON serialization of state.labels before marshaling the complete normalized event. Labels are the only unbounded list a normalized event carries, and anyone who can label the work item controls their count, so without such a bound an author could push the complete event past the transport budget and force buildEventPayload's comment-only fallback — the same attacker-chosen "no event" channel TransportStringRefLimit's rationale closes. The bound is unconditional (an event whose labels exceed it arrives truncated even when the complete payload would have fit without it — a documented behavior change), and together with the body and single-string bounds it keeps the worst attacker-shaped payload inside the transport budget, which TestBuildEventPayload_WorstCaseFitsTransportBudget pins.

Variables

View Source
var ErrTransportBudget = errors.New("dispatch transport budget exceeded")

ErrTransportBudget marks a dispatch refused because its payload cannot fit the transport budget (the poller's maxEventPayloadChunks * dispatchPayloadChunkSize base64 characters). The refusal is deterministic — the same event re-marshals to the same oversized payload — so it is permanent for that event: the GitLab poller (internal/poll's dispatch loop) drops the event without spending its retry budget, and the Jira poller (internal/jirapoll's checkpoint commit) advances the issue's checkpoint past the refused record, instead of either wedging the entity behind an endless retry of a refusal that cannot succeed. The webhook dispatcher (internal/poll's webhook dispatch step) is the third consumer: it fails its job with the error — a re-run or payload replay re-refuses the event — instead of dropping or advancing. The refusal sites in internal/poll (dispatch()'s outer budget check, buildEventPayload's command-note fail-closed and encodeJiraEventPayload's budget error) wrap it, so pollers match it with errors.Is.

Functions

func BoundTransportLabels added in v0.56.0

func BoundTransportLabels(labels []string) []string

BoundTransportLabels returns labels unchanged when their JSON serialization fits TransportLabelsLimit, and otherwise the longest prefix that does — plus every control label the prefix dropped (IsControlLabel): the router's no-fix gate and the shipped agent triggers evaluate the bounded list, so a stop label pushed past the byte cap by padding labels would fail that gate open, and a kill switch must survive its own transport bound. The kept control labels (~32 JSON bytes for both) ride inside the worst-case budget margin (TestBoundTransportLabels_KeepsControlLabels pins both the keep and the budget fit), and keeping one can only suppress or enable what the gates already decided — anyone who can label the work item can add or remove the label itself.

func HasRole added in v0.33.0

func HasRole(actorRole, required string) bool

HasRole reports whether actorRole meets or exceeds the required role level. Returns false if required is not a recognized role string, so a typo in the required parameter fails closed rather than silently passing.

func IsControlLabel added in v0.56.0

func IsControlLabel(label string) bool

IsControlLabel reports whether label is one of fullsend's own control labels — the labels the router's gates and the shipped agent triggers evaluate as control flow rather than data (the fix gate's stop and opt-in labels; docs/agents/fix.md's Control labels section). The transport labels bound (transport.go in this package) keeps them even past its byte cap: the router matches on the bounded list, and dropping a stop label under padding labels would fail that gate open — a kill switch must survive its own transport bound. Keeping a control label can only suppress or enable what the gates already decided, never widen it: anyone who can label the work item can also add or remove the label itself.

func LogBoundTransportLabels added in v0.56.0

func LogBoundTransportLabels(where string, labels []string) []string

LogBoundTransportLabels bounds labels like BoundTransportLabels and logs a one-line WARNING when entries were dropped past the bound. Exported for the GitLab dispatch door (internal/poll, which applies it to the transported payload's state.labels) and for the Jira poller's GitLab-target door (internal/jirapoll), which applies the same bound before CEL trigger matching so the matcher and the transported payload agree on state.labels: a trigger keyed on a label past the bound does not match there, exactly as the transported event lacks it.

func RoleLevel added in v0.33.0

func RoleLevel(role string) int

RoleLevel returns the numeric level for a normalized role string. The hierarchy is: none(0) < read(1) < triage(2) < write(3) < maintain(4) < admin(5). Unknown roles return 0.

Types

type Actor added in v0.32.0

type Actor struct {
	ID               string `json:"id"`
	Kind             string `json:"kind"`
	Role             string `json:"role"`
	IsEntityAuthor   bool   `json:"is_entity_author"`
	IsEntityAssignee bool   `json:"is_entity_assignee"`
}

Actor identifies who triggered the event.

type ChangeProposalState added in v0.32.0

type ChangeProposalState struct {
	ID       int    `json:"id"`
	HeadRepo string `json:"head_repo"`
	BaseRepo string `json:"base_repo"`
	HeadRef  string `json:"head_ref"`
	BaseRef  string `json:"base_ref"`
	HeadSHA  string `json:"head_sha,omitempty"`
	AuthorID string `json:"author_id"`
	IsFork   bool   `json:"is_fork"`
}

ChangeProposalState carries MR/PR metadata needed by stages.

type Dispatcher

type Dispatcher interface {
	// Name returns a human-readable identifier (e.g. "gcf").
	Name() string

	// Provision creates the dispatch infrastructure and returns
	// org-level variables to store (e.g. mint URL).
	Provision(ctx context.Context) (variables map[string]string, err error)

	// StoreAgentPEM persists a role's PEM key in the mint's secret store.
	// Called once per role during App setup so partial failures are survivable.
	StoreAgentPEM(ctx context.Context, role string, pem []byte) error

	// OrgSecretNames returns the names of org-level secrets this
	// dispatcher manages.
	OrgSecretNames() []string

	// OrgVariableNames returns the names of org-level variables this
	// dispatcher manages.
	OrgVariableNames() []string
}

Dispatcher provisions dispatch infrastructure during install.

type Entity added in v0.32.0

type Entity struct {
	Kind                 string                `json:"kind"`
	ID                   int                   `json:"id"`
	URL                  string                `json:"url"`
	Key                  string                `json:"key,omitempty"`
	LinkedChangeProposal *LinkedChangeProposal `json:"linked_change_proposal,omitempty"`
}

Entity identifies the work item or change proposal the event acts on.

type EventRouter added in v0.32.0

type EventRouter interface {
	Route(event *NormalizedEvent) ([]string, error)
}

EventRouter routes a NormalizedEvent to zero or more stage names.

type HarnessRouter added in v0.33.0

type HarnessRouter struct {
	// contains filtered or unexported fields
}

HarnessRouter implements EventRouter by applying the default routing rules from ADR 0067's event routing table. Slash commands (/fs-X) dispatch to any agent in the valid set; label, merge, MR-open, and MR-push (synchronized) events use hardcoded stage mappings.

This is an interim implementation using Go routing rules. ADR 0067 prescribes CEL trigger expressions (ADR 0061) for routing; this hard-coded router will be replaced once the CEL evaluation engine is available in the dispatch core.

func NewHarnessRouter added in v0.33.0

func NewHarnessRouter(agentNames []string) *HarnessRouter

NewHarnessRouter creates a router that accepts the given agent names as valid dispatch targets. Names are stored lowercase for case-insensitive matching.

func (*HarnessRouter) Route added in v0.33.0

func (r *HarnessRouter) Route(event *NormalizedEvent) ([]string, error)

Route determines which stages (if any) should handle the event.

type LinkedChangeProposal added in v0.32.0

type LinkedChangeProposal struct {
	ID  int    `json:"id"`
	URL string `json:"url"`
}

LinkedChangeProposal links a work_item entity to its associated change proposal.

type NormalizedEvent added in v0.32.0

type NormalizedEvent struct {
	Repo       string     `json:"repo"`
	Entity     Entity     `json:"entity"`
	Transition Transition `json:"transition"`
	Actor      Actor      `json:"actor"`
	State      State      `json:"state"`
	Source     Source     `json:"source"`
}

NormalizedEvent is the forge-neutral routing input for dispatch and harness CEL trigger evaluation. See docs/normative/normalized-event/v1/. This type intentionally uses plain strings (not typed enums) to keep the dispatch package free of normevent dependencies; the poll layer is the only producer, and child pipelines consume JSON.

type Source added in v0.32.0

type Source struct {
	System    string `json:"system"`
	RawType   string `json:"raw_type"`
	RawAction string `json:"raw_action,omitempty"`
}

Source records event provenance.

type State added in v0.32.0

type State struct {
	Labels         []string             `json:"labels"`
	ChangeProposal *ChangeProposalState `json:"change_proposal,omitempty"`
}

State captures the entity's state at event time. ChangeProposal is nil when MR metadata is unavailable (e.g., fast-poll mode or failed project-path resolution). Routers MUST treat nil as "unknown" and deny fork-sensitive stages by default.

type Transition added in v0.32.0

type Transition struct {
	Kind    string             `json:"kind"`
	Label   *TransitionLabel   `json:"label,omitempty"`
	Comment *TransitionComment `json:"comment,omitempty"`
	Review  *TransitionReview  `json:"review,omitempty"`
}

Transition describes the lifecycle event that occurred.

type TransitionComment added in v0.32.0

type TransitionComment struct {
	Command     string `json:"command,omitempty"`
	Body        string `json:"body"`
	Instruction string `json:"instruction,omitempty"`
}

TransitionComment carries comment details (kind == "comment_added").

type TransitionLabel added in v0.32.0

type TransitionLabel struct {
	Name   string `json:"name"`
	Action string `json:"action"`
}

TransitionLabel carries label change details (kind == "label_changed").

type TransitionReview added in v0.32.0

type TransitionReview struct {
	State      string `json:"state"`
	ReviewerID string `json:"reviewer_id"`
}

TransitionReview carries review details (kind == "review_submitted").

Directories

Path Synopsis
cf
Package cf implements the dispatch.Dispatcher interface using a Cloudflare Worker as the token mint.
Package cf implements the dispatch.Dispatcher interface using a Cloudflare Worker as the token mint.
workersrc
Package workersrc exposes the Worker's npm manifest and lock file to Go callers.
Package workersrc exposes the Worker's npm manifest and lock file to Go callers.
Package gcf implements the dispatch.Dispatcher interface using a GCP Cloud Function as the token mint.
Package gcf implements the dispatch.Dispatcher interface using a GCP Cloud Function as the token mint.

Jump to

Keyboard shortcuts

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