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
- Variables
- func BoundTransportLabels(labels []string) []string
- func HasRole(actorRole, required string) bool
- func IsControlLabel(label string) bool
- func LogBoundTransportLabels(where string, labels []string) []string
- func RoleLevel(role string) int
- type Actor
- type ChangeProposalState
- type Dispatcher
- type Entity
- type EventRouter
- type HarnessRouter
- type LinkedChangeProposal
- type NormalizedEvent
- type Source
- type State
- type Transition
- type TransitionComment
- type TransitionLabel
- type TransitionReview
Constants ¶
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 ¶
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
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
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
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
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.
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
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
TransitionLabel carries label change details (kind == "label_changed").
type TransitionReview ¶ added in v0.32.0
TransitionReview carries review details (kind == "review_submitted").
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |