dispatch

package
v0.46.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 4 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

This section is empty.

Variables

This section is empty.

Functions

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 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"`
}

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, and MR-open 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
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.
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