Documentation
¶
Overview ¶
Package poll implements the GitLab cron-polling event dispatch loop. It discovers events from the GitLab API, converts them to NormalizedEvents, routes them through the dispatch core, and dispatches agent stages via API-triggered pipelines.
Index ¶
- Constants
- func EnsureDispatchSecret(ctx context.Context, client forge.Client, owner, repo string) (secret string, created bool, err error)
- func SeedGitLabPollStateBranches(ctx context.Context, client forge.Client, owner, repo, dispatchSecret string) (bool, error)
- type Dispatch
- type EventNote
- type GitLabClient
- type Issue
- type LabelAuthor
- type LabelState
- type MergeRequest
- type Note
- type Options
- type Poller
- type ProjectEvent
- type ResourceLabelEvent
- type RoutableEvent
- type UserRef
Constants ¶
const ( // PollStateBranchSlash is written by the slash poll (*/5). PollStateBranchSlash = "fullsend-poll-state-slash" // PollStateBranchEvents is written by the event poll (2,17,32,47). PollStateBranchEvents = "fullsend-poll-state-events" // PollStateFileName is the single HMAC-signed document on each branch. PollStateFileName = "state.json" )
Poller state lives on two dedicated, unprotected branches so the bot PAT can run at Developer access (30) instead of Maintainer (40). Each poll mode owns its own branch so concurrent slash+events runs cannot clobber each other, and force-re-root pruning cannot drop a sibling file. See #7343 and ADR 0067.
Variables ¶
This section is empty.
Functions ¶
func EnsureDispatchSecret ¶ added in v0.44.0
func EnsureDispatchSecret(ctx context.Context, client forge.Client, owner, repo string) (secret string, created bool, err error)
EnsureDispatchSecret returns the project's existing FULLSEND_DISPATCH_SECRET CI/CD variable value, or generates and stores a new one (masked, protected, like the bot PAT) if none is set. created is true when a new secret was written. Without this, poll-state HMAC signing requires a manual operator step and the poller fails closed.
func SeedGitLabPollStateBranches ¶ added in v0.44.0
func SeedGitLabPollStateBranches(ctx context.Context, client forge.Client, owner, repo, dispatchSecret string) (bool, error)
SeedGitLabPollStateBranches creates both poll-state branches with an HMAC-signed state.json, using the operator's Maintainer-capable client so legacy CI/CD variables can still be read. *Fast fields are written to the slash branch; *Full fields plus LabelState go to the events branch.
A missing branch is seeded from any present legacy variables, or with an empty signed baseline when none are present. An already-present state.json is left untouched so live poller writes are not clobbered. dispatchSecret must be non-empty: unsigned documents would be discarded as tampered by the runtime poller.
Returns true if at least one branch was written.
Types ¶
type Dispatch ¶
type Dispatch struct {
Stage string `json:"stage"`
EventType string `json:"event_type"`
EventPayloadB64 string `json:"event_payload_b64"`
ResourceKey string `json:"resource_key"`
MRAuthorID int `json:"mr_author_id,omitempty"`
ActorID int `json:"actor_id,omitempty"`
IsFork bool `json:"is_fork"`
IID int `json:"iid,omitempty"`
}
Dispatch represents a single API-triggered pipeline dispatch record.
type EventNote ¶
type EventNote struct {
ID int `json:"id"`
NoteableType string `json:"noteable_type"`
NoteableIID int `json:"noteable_iid"`
Body string `json:"body"`
}
EventNote is the embedded note object in a project event.
type GitLabClient ¶
type GitLabClient interface {
ListIssuesUpdatedSince(ctx context.Context, owner, repo string, since time.Time) ([]Issue, error)
ListMergeRequestsUpdatedSince(ctx context.Context, owner, repo string, since time.Time) ([]MergeRequest, error)
// ListProjectEvents returns events matching targetType (use lowercase
// "note" for the request param). The after parameter is date-only
// (ISO 8601 date, exclusive): implementations must widen to at least
// since.AddDate(0,0,-1) and apply client-side timestamp filtering.
ListProjectEvents(ctx context.Context, owner, repo string, targetType string, after time.Time) ([]ProjectEvent, error)
// ListIssueNotes MUST return notes in ascending created_at order.
ListIssueNotes(ctx context.Context, owner, repo string, issueIID int) ([]Note, error)
ListMergeRequestNotes(ctx context.Context, owner, repo string, mrIID int) ([]Note, error)
// ListResourceLabelEvents MUST return events in ascending ID order
// (the poller iterates in reverse to find the most recent "add").
ListResourceLabelEvents(ctx context.Context, owner, repo string, issueIID int) ([]ResourceLabelEvent, error)
// GetFileContentAtRef retrieves a file at a specific ref (branch,
// tag, or SHA). Returns forge.ErrNotFound if the file or ref does
// not exist. Used to load the HMAC-signed poll-state document.
GetFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)
// GetBranchRef returns the HEAD commit SHA for the named branch.
// Returns forge.ErrNotFound if the branch does not exist. Used to
// pin the CAS parent SHA at poll-state load time.
GetBranchRef(ctx context.Context, owner, repo, branch string) (string, error)
// CommitFileToBranch commits a single file to branch without force.
// expectedSHA is the branch tip observed at load time and is sent as
// start_sha so a concurrent writer surfaces forge.ErrNonFastForward.
// An empty expectedSHA (no branch observed at load time) still commits
// with start_sha pinned to the repository root, but leaves force unset
// so a concurrent first writer racing branch creation surfaces the same
// forge.ErrNonFastForward instead of being silently overwritten.
// The commit message is suffixed with [skip ci] when not already present.
CommitFileToBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte, expectedSHA string) error
// ForceCommitFileToBranch force-updates branch to a single-file
// commit re-rooted on a fixed base SHA. The branch is created if
// it does not exist. History is pruned to base + 1 commit.
// Used for install-time seeding; runtime persist uses CommitFileToBranch.
ForceCommitFileToBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
// DeleteRef deletes a git ref (e.g., "heads/fullsend-poll-state-slash").
// Returns forge.ErrNotFound if the ref does not exist. Used to
// discard a tampered poll-state branch.
DeleteRef(ctx context.Context, owner, repo, refPath string) error
GetAuthenticatedUser(ctx context.Context) (string, error)
GetAuthenticatedUserID(ctx context.Context) (int, error)
// CreateNoteAwardEmoji adds an emoji reaction. noteableType must be
// "Issue" or "MergeRequest" to select the correct API endpoint.
CreateNoteAwardEmoji(ctx context.Context, owner, repo string, noteableType string, noteableIID, noteID int, emoji string) error
GetIssue(ctx context.Context, owner, repo string, issueIID int) (*Issue, error)
GetMergeRequest(ctx context.Context, owner, repo string, mrIID int) (*MergeRequest, error)
// GetMemberAccessLevel returns the access level for a project member.
// Implementations MUST use the /members/all/:user_id endpoint to
// include inherited (group-level) membership, not /members/:user_id
// which only returns direct members.
GetMemberAccessLevel(ctx context.Context, owner, repo string, userID int) (int, error)
GetProjectPath(ctx context.Context, projectID int) (string, error)
// CreatePipeline creates a new pipeline on the given ref with the
// given variables. Returns the pipeline ID and web URL.
CreatePipeline(ctx context.Context, owner, repo, ref string, variables map[string]string) (int64, string, error)
}
GitLabClient defines the GitLab API surface the poller requires. This interface is separate from forge.Client because the poller needs GitLab-specific methods (label events, project events) that are not part of the forge-neutral abstraction. Phase 1 wiring will provide a concrete type that satisfies this interface, backed by the forge.Client credential and HTTP plumbing.
All List* methods MUST exhaust pagination (per_page=100, follow x-next-page) and return the complete result set. Returning only page 1 (GitLab default: 20 items) causes silent event loss.
type Issue ¶
type Issue struct {
IID int `json:"iid"`
Title string `json:"title"`
State string `json:"state"`
Labels []string `json:"labels"`
Author UserRef `json:"author"`
UpdatedAt time.Time `json:"updated_at"`
}
Issue represents a GitLab issue as returned by the API. Author is a nested object in the GitLab v4 response.
type LabelAuthor ¶
LabelAuthor identifies who applied a label.
type LabelState ¶
LabelState tracks previously-seen labels per issue IID.
type MergeRequest ¶
type MergeRequest struct {
IID int `json:"iid"`
Title string `json:"title"`
State string `json:"state"`
Labels []string `json:"labels"`
SourceProjectID int `json:"source_project_id"`
TargetProjectID int `json:"target_project_id"`
SourceBranch string `json:"source_branch"`
TargetBranch string `json:"target_branch"`
Author UserRef `json:"author"`
MergeUser UserRef `json:"merge_user"`
MergedBy UserRef `json:"merged_by"`
ClosedBy UserRef `json:"closed_by"`
MergedAt time.Time `json:"merged_at"`
ClosedAt time.Time `json:"closed_at"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
MergeRequest represents a GitLab merge request as returned by the API. Fields are derived from nested API objects (author, merge_user); GitLab does not expose flat author_id/merged_by_id fields on MRs.
type Note ¶
type Note struct {
ID int `json:"id"`
Body string `json:"body"`
Author UserRef `json:"author"`
CreatedAt time.Time `json:"created_at"`
}
Note represents a GitLab note (comment) on an issue or MR.
type Options ¶
type Options struct {
BotUserID int
GitLabURL string
PipelineRef string // git ref for API-triggered pipelines (required; resolved at CLI wiring time)
PollJobURL string // back-link to the poller CI job (optional; from CI_JOB_URL)
DispatchSecret string // HMAC shared secret for signing dispatch variables (optional; from FULLSEND_DISPATCH_SECRET)
Mode string // "slash" (slash commands only) or "events" (full discovery, filters /fs-* notes); empty uses events discovery path but includes all notes for backward compatibility
}
Options configures the poller.
type Poller ¶
type Poller struct {
// contains filtered or unexported fields
}
Poller discovers GitLab events and dispatches agent stages.
func New ¶
func New(client GitLabClient, router dispatch.EventRouter, projectPath string, opts Options) *Poller
New creates a Poller for the given project.
func (*Poller) Run ¶
Run executes a single poll cycle: read watermark, discover events, filter, deduplicate, convert to NormalizedEvent, route, dispatch, and advance the watermark.
Conversion, routing, and dispatch failures are returned after poll state is persisted so the poll job fails instead of reporting a healthy cycle. Failed events remain retryable until maxEventRetries. The cycle that exhausts the budget also fails (the event is dropped); later rediscovery of an already-dropped event is a skip, not a new failure, so the 30s watermark overlap cannot pin the poll job red.
Poll mode is determined by Options.Mode:
- "slash": fast poll — only /fs-* slash commands via the Events API
- "events": full discovery — labels, merges, MR opens, closed-unmerged MRs, non-slash notes (filters out /fs-* notes)
- "": backward compatibility — uses events discovery path but does not filter /fs-* notes
type ProjectEvent ¶
type ProjectEvent struct {
ID int `json:"id"`
Author UserRef `json:"author"`
Note EventNote `json:"note"`
CreatedAt time.Time `json:"created_at"`
}
ProjectEvent represents an event from the GitLab Events API.
type ResourceLabelEvent ¶
type ResourceLabelEvent struct {
ID int `json:"id"`
Action string `json:"action"`
Label struct {
Name string `json:"name"`
} `json:"label"`
User UserRef `json:"user"`
}
ResourceLabelEvent represents a label change event from the GitLab API.
type RoutableEvent ¶
type RoutableEvent struct {
Type string
Action string // MR lifecycle action for Type=="mr_event": "opened", "closed", or empty (merged)
IID int
UpdatedAt time.Time
Labels []string // full label set at event time
ChangedLabel string // the label that was added/removed (label events only)
NoteBody string
NoteID int
NoteAuthorID int
NoteAuthorLogin string
IsBot bool
MRSource int
MRTarget int
SourceBranch string
TargetBranch string
MRAuthorID int
MRAuthorLogin string
MergedByLogin string
}
RoutableEvent is an intermediate representation of a detected change, produced by event discovery and consumed by the poll loop for NormalizedEvent conversion and dispatch.
func (RoutableEvent) Key ¶
func (e RoutableEvent) Key() string
Key returns a deduplication key for the event. Note events use their globally unique NoteID. Label events include UpdatedAt so that a remove-then-re-add of the same label produces a distinct key. MR open events include Action so they do not collide with a merge of the same IID in the same second. MR merge events use type+IID+timestamp (Action empty) for stable dispatched-key persistence.