server

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 38 Imported by: 0

Documentation

Overview

Package server is the dispatcher's HTTP API (design/workstreams/dispatcher-runtime/LLD/ api-server.md): the generated Echo strict server (internal/apiserver/gen) implemented over the scheduler, the controllers, the store and the provider connections; the webhook routes delegated to each provider's Conn.Handler; SSE; and the localhost ops listener (healthz, readyz, metrics).

Middleware, in order: request ID → access log (no bodies, no query strings) → recover → auth (per operation) → body limit (1 MB; transcripts 20 MB) → handler. Every error is rendered as application/problem+json by one HTTPErrorHandler.

Index

Constants

View Source
const (
	MaxIdempotencyKey          = 200
	MaxEffectsPerRun           = 60
	MaxCommentsPerRun          = 20
	MaxCommentsPerWorkItemHour = 30
)

Effector limits (api-server.md §Effector API).

View Source
const (
	LabelEffectTask     = "factory.ccf.dev/task"
	LabelEffectRun      = "factory.ccf.dev/run"
	LabelEffectWorkItem = "factory.ccf.dev/workitem"
)

Labels on the Effects the Effector records.

View Source
const (
	HeaderJoinToken         = "X-Factory-Join-Token"
	HeaderOwnerToken        = "X-Factory-Owner-Token"
	HeaderEnrollmentToken   = "X-Factory-Enrollment-Token"
	HeaderAgentRefreshToken = "X-Factory-Agent-Refresh-Token"
)

Registration headers: the enrollmentToken and agentRefreshToken security schemes, and the join and owner token headers of the removed device flow, which are refused with a hint.

View Source
const (
	CodeUnauthenticated        = "unauthenticated"
	CodeForbidden              = "forbidden"
	CodeNotMember              = "not-a-member"
	CodeNotAdmin               = "not-admin"
	CodeCrossSite              = "cross-site-request"
	CodeNotLeaseHolder         = "not-lease-holder"
	CodeNotYourAgent           = "not-your-agent"
	CodeLeaseGone              = "lease-gone"
	CodeInvalid                = "invalid-request"
	CodeNotFound               = "not-found"
	CodeConflict               = "conflict"
	CodeTooLarge               = "payload-too-large"
	CodeIdempotencyKeyRequired = "idempotency-key-required"
	CodeEffectNotAllowed       = "effect-not-allowed"
	CodeLabelNotAllowed        = "label-not-allowed"
	CodeTargetNotAllowed       = "target-not-allowed"
	CodeRateLimited            = "rate-limited"
	CodeProviderRetryable      = "provider-retryable"
	CodeProviderError          = "provider-error"
	CodeStateMismatch          = "oauth-state-mismatch"
	CodeBadReturnTo            = "bad-return-to"
	CodeOAuth                  = "oauth-failed"
	CodeCatalogNotLoaded       = "catalog-not-loaded"
	CodeUnavailable            = "unavailable"
	CodeTooManySubscribers     = "too-many-subscribers"
	CodeTaskNotActive          = "task-not-active"
	CodeWorkItemGone           = "workitem-gone"
	CodeNotInCatalog           = "not-in-catalog"
	CodeNotCompilable          = "not-compilable"
	CodeInternal               = "internal"
	CodeNotImplemented         = "not-implemented"
	// CodeStoreReadOnly: the store has stopped writing (it met an entry written by a newer
	// release than this one reads); reads go on (503).
	CodeStoreReadOnly = "store-read-only"
)

Problem codes (Problem.code), stable for clients.

View Source
const (
	DefaultBodyLimit       = 1 << 20  // 1 MB
	DefaultTranscriptLimit = 20 << 20 // 20 MB, the store's per-transcript cap
	DefaultMaxSubscribers  = 100
	DefaultKeepAlive       = 15 * time.Second
	DefaultLeaseWait       = 30 * time.Second
	MaxLeaseWait           = 60 * time.Second
	DefaultPageSize        = 100
	MaxPageSize            = 500
)

Defaults for Options.

View Source
const (
	SSEProgress        = "progress"
	SSEWorkItemUpdated = "workitem.updated"
	SSETaskUpdated     = "task.updated"
	SSEAgentUpdated    = "agent.updated"
)

SSE event names.

View Source
const BasePath = "/api/v1"

BasePath is where the generated API is mounted.

View Source
const CodeAppNotInstalled = "app-not-installed"

CodeAppNotInstalled is the getCatalog warning of an identity's App that isn't installed on a repo the catalog can touch.

View Source
const CodeReplayHistoryGone = "replay-history-gone"

CodeReplayHistoryGone is replayEvent's 409 for an event whose earlier decisions aged out of its work item.

View Source
const CodeTaskLeased = "task-leased"

CodeTaskLeased is deleteWorkItem's 409 without force while one of the item's tasks is leased.

View Source
const EnvironmentLogRefPrefix = "blob://environment-logs/"

EnvironmentLogRefPrefix starts an environment log reference (uploadEnvironmentLog's environmentLogRef, Run.status.environmentLogRef).

View Source
const InjectedEventPrefix = "inject/"

InjectedEventPrefix starts the id of a dispatched event that came without one.

View Source
const MediaTypeSchemaJSON = "application/schema+json"

MediaTypeSchemaJSON is getTaskOutputSchema's media type.

View Source
const ProblemContentType = "application/problem+json"

ProblemContentType is the media type of every error body (RFC 9457).

View Source
const TranscriptRefPrefix = "blob://transcripts/"

TranscriptRefPrefix starts a transcript reference (uploadTranscript's transcriptRef).

Variables

This section is empty.

Functions

This section is empty.

Types

type CatalogResyncer

type CatalogResyncer interface {
	Resync()
}

CatalogResyncer is the resync-catalog command (*controllers.CatalogSync).

type CatalogStatus

type CatalogStatus interface {
	Status() controllers.CatalogStatus
}

CatalogStatus reports catalog-sync's status (*controllers.CatalogSync).

type Content

type Content struct {
	MediaType string
	Text      string
	// Author is who wrote it (login), for the fence's label.
	Author string
}

Content is an object's text, as a ContentReader returns it.

type ContentReader

type ContentReader interface {
	ReadContent(ctx context.Context, ref v1alpha1.ObjectRef) (Content, error)
}

ContentReader is implemented by provider connections that can read an object's untrusted text (title, body, comments) for a task's context items. provider.Conn has no such method yet (Observe carries no untrusted text), so a connection without it yields reference-only items.

type Deps

type Deps struct {
	Store       store.Store
	Transcripts store.TranscriptStore
	Catalog     controllers.CatalogProvider
	// CatalogStatus and Resync are catalog-sync; optional (no status: the catalog is
	// "loaded" once Current is set; no resync: resync-catalog is 503).
	CatalogStatus CatalogStatus
	Resync        CatalogResyncer
	// Installations are the missing App installations, shown as getCatalog warnings;
	// optional.
	Installations InstallationReporter
	Conns         controllers.ConnSource
	// Sink receives webhook deliveries (the provider controller's sink).
	Sink         provider.IngressSink
	Scheduler    Scheduler
	Factory      *controllers.FactoryProvider
	KillSwitches KillSwitchWriter
	Evaluator    Evaluator
	// Replayer is replayEvent's; optional (none: 503).
	Replayer Replayer
	Auth     *auth.Authenticator
	// Skills resolves a redispatched task's skills (the rule controller's resolver); nil:
	// controllers.KeepSkills.
	Skills controllers.SkillResolver
}

Deps are what the server works with.

type DropCounter added in v0.2.0

type DropCounter interface {
	Drops() []controllers.DropCount
}

DropCounter counts the events the intake filter dropped (*controllers.ProviderController).

type Evaluator

type Evaluator interface {
	DryRun(ctx context.Context, ev v1alpha1.Event, workItem string) (rules.Evaluation, error)
}

Evaluator is the dry-run: the rule controller's evaluation of an event, with nothing applied (*controllers.RuleController).

type InstallationReporter

type InstallationReporter interface {
	Gaps() []controllers.InstallationGap
}

InstallationReporter reports the App installations the catalog misses (*controllers.InstallationCheck).

type KillSwitchWriter

type KillSwitchWriter interface {
	Pause(ctx context.Context, scope, name, by string, at time.Time) error
	Resume(ctx context.Context, scope, name string) error
}

KillSwitchWriter sets and clears the pause flags (controllers.StoreKillSwitches).

type Options

type Options struct {
	// PublicURL is the dispatcher's public base URL; its origin is the only one cookie-
	// authenticated writes are accepted from. Empty: the request's own host.
	PublicURL string
	// CatalogRepo and CatalogRef describe the catalog source for GET /catalog.
	CatalogRepo string
	CatalogRef  string
	// Controllers are reported on /metrics (factory_controller_panics_total).
	Controllers []*controllers.Controller
	// Intake reports the events the provider controller's intake filter dropped, on /metrics
	// (factory_events_dropped_total). Nil: none reported.
	Intake DropCounter
	// MaxSubscribers bounds the SSE streams (default 100).
	MaxSubscribers int
	// KeepAlive is the SSE keep-alive interval (default 15 s).
	KeepAlive time.Duration
	// BodyLimit and TranscriptLimit bound request bodies (1 MB, 20 MB).
	BodyLimit       int64
	TranscriptLimit int64
	Clock           clock.Clock
	Logger          *slog.Logger
}

Options configure the server. Zero fields take the defaults.

type Replayer

type Replayer interface {
	Replay(ctx context.Context, event string) (controllers.ReplayResult, error)
}

Replayer replays a stored event through the rules (*controllers.RuleController).

type Scheduler

type Scheduler interface {
	Register(ctx context.Context, req scheduler.RegisterRequest) (*scheduler.Registration, error)
	UpdateAgent(ctx context.Context, agentID string, u scheduler.AgentUpdate) (*v1alpha1.Agent, error)
	Deregister(ctx context.Context, agentID string) error
	Lease(ctx context.Context, agentID string, wait time.Duration) (*scheduler.Grant, error)
	Heartbeat(ctx context.Context, agentID, leaseID string, req scheduler.HeartbeatRequest) (*scheduler.HeartbeatResponse, error)
	Complete(ctx context.Context, agentID, leaseID string, res v1alpha1.Result) (v1alpha1.TaskPhase, error)
	Abandon(ctx context.Context, agentID, leaseID string, req scheduler.AbandonRequest) error
	CreateEnrollment(ctx context.Context, req scheduler.EnrollRequest) (*scheduler.Enrollment, string, error)
	ListEnrollments(ctx context.Context) ([]*scheduler.Enrollment, error)
	DeleteEnrollment(ctx context.Context, id string) error
	RevokeRefresh(ctx context.Context, agentID string) error
}

Scheduler is what the server calls for agents and leases (*scheduler.Scheduler).

type Server

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

Server is the API server. Handler serves the public API (mount the UI on Echo() as the catch-all); OpsHandler serves the ops routes, for the localhost listener only.

func New

func New(d Deps, opts Options) (*Server, error)

New returns a server.

func (*Server) AbandonLease

AbandonLease implements gen.StrictServerInterface.

func (*Server) AuthCallback

AuthCallback implements gen.StrictServerInterface: checks the state against its cookie, exchanges the code, sets the session cookie and redirects to the returnTo path.

func (*Server) CloseWorkItem

CloseWorkItem implements gen.StrictServerInterface (api-server.md §Commands): it sets status.closed, cancels the item's active tasks and records a decision (controllers.CloseWorkItem).

func (*Server) CompleteLease

CompleteLease implements gen.StrictServerInterface. It goes through Scheduler.Complete (not the run controller's), which tops up the usage and ends the lease.

func (*Server) CreateEffect

CreateEffect implements gen.StrictServerInterface: the Effector API.

  1. the agent holds the task's active lease (403 not-lease-holder);
  2. the op is in the task's effects.allow (403 effect-not-allowed);
  3. every label the op's args name (labelArgs: label.add/remove, create-issue and pr.open labels, pr.merge's mergeLabel) matches effects.labels (403 label-not-allowed);
  4. the target is the task's repo, an object in it, or a work item link (403 target-not-allowed);
  5. the idempotency key is present (≤ 200 chars; 400 idempotency-key-required); a known key returns the stored Effect;
  6. rate limits (429 rate-limited);
  7. API ops: Conn.Apply as the task's identity (a retryable provider error is 429 with Retry-After); git-side ops are only recorded;
  8. the object a creating op made (creatingOps) is linked to the task's work item, on a provider replay too;
  9. the Effect is stored and appended to the run's progress (which the SSE stream sends).

func (*Server) CreateEnrollment

CreateEnrollment implements gen.StrictServerInterface (P1 §6): an admin mints a one-time enrollment token for a pool, an owner and a name. The owner's login is on the dispatcher's sign-in provider; the token is returned only here.

func (*Server) DeleteEnrollment

DeleteEnrollment implements gen.StrictServerInterface: an unused enrollment's token stops working; a used one's record goes, and its agent stays.

func (*Server) DeleteWorkItem

DeleteWorkItem implements gen.StrictServerInterface (api-server.md §Commands): it deletes the item and everything keyed to it (controllers.DeleteWorkItem), then the scheduler's leases of its tasks. A leased task refuses it (409 task-leased) unless force.

func (*Server) DeregisterAgent

DeregisterAgent implements gen.StrictServerInterface. The agent deregisters itself; an admin's delete (a UI admin or the CLI token, agentOrAdmin) also revokes the agent's refresh token, so it can't register again without a new enrollment.

func (*Server) DryRunCatalog

DryRunCatalog implements gen.StrictServerInterface: the rule controller's evaluation of the event, with nothing stored or applied.

func (*Server) Echo

func (s *Server) Echo() *echo.Echo

Echo is the public Echo instance, for `factory serve` to mount the UI catch-all on.

func (*Server) GetCatalog

GetCatalog implements gen.StrictServerInterface: the live catalog's commit, the sync status and errors, and the objects it holds.

func (*Server) GetCatalogFile

GetCatalogFile implements gen.StrictServerInterface: one prompt template or JSON Schema of the live catalog, unrendered. A path outside prompts/ and schemas/, or not in its canonical form (.., //, a trailing /), is a 400; the lookup is in the snapshot's maps only.

func (*Server) GetCatalogObject

GetCatalogObject implements gen.StrictServerInterface.

func (*Server) GetEnvironmentLog

GetEnvironmentLog implements gen.StrictServerInterface: the stored environment log, as uploaded, for a UI reader or the CLI.

func (*Server) GetMe

GetMe implements gen.StrictServerInterface.

func (*Server) GetRun

GetRun implements gen.StrictServerInterface: the run and the effects it made.

func (*Server) GetTask

GetTask implements gen.StrictServerInterface.

func (*Server) GetTaskContext

GetTaskContext implements gen.StrictServerInterface: context item n, with untrusted content fenced and labelled.

func (*Server) GetTaskOutputSchema

GetTaskOutputSchema implements gen.StrictServerInterface: the output schema the task's Result is validated against on complete (controllers.ResultSpec: the live catalog's), as the catalog holds it. An agent may read only the task it holds the lease of, and a run token only its lease's task; UI and CLI any task (getTask's rule).

func (*Server) GetTaskPrompt

GetTaskPrompt implements gen.StrictServerInterface.

func (*Server) GetTranscript

GetTranscript implements gen.StrictServerInterface: a UI reader, or the agent holding the run's lease.

func (*Server) GetWorkItem

GetWorkItem implements gen.StrictServerInterface: the work item and its timeline (events, tasks, runs, effects).

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler is the public API: /api/v1 and /hooks/{provider}.

func (*Server) HeartbeatLease

HeartbeatLease implements gen.StrictServerInterface.

func (*Server) LeaseTask

LeaseTask implements gen.StrictServerInterface: the long poll. 204 when nothing matched in time.

func (*Server) ListAgents

ListAgents implements gen.StrictServerInterface: by name.

func (*Server) ListCatalogFiles

ListCatalogFiles implements gen.StrictServerInterface: the live catalog's prompt templates and JSON Schemas, by path. They come from the loaded snapshot, never from disk.

func (*Server) ListEnrollments

ListEnrollments implements gen.StrictServerInterface: a page of enrollments, never their tokens or hashes.

func (*Server) ListPools

ListPools implements gen.StrictServerInterface: each pool with its registered agents.

func (*Server) ListProviders

ListProviders implements gen.StrictServerInterface: each provider with its connection's health (unknown when not connected).

func (*Server) ListQueues

ListQueues implements gen.StrictServerInterface: each queue with its depth, running tasks and pending tasks with the reason each waits.

func (*Server) ListTasks

ListTasks implements gen.StrictServerInterface: newest first.

func (*Server) ListWorkItems

ListWorkItems implements gen.StrictServerInterface: most recently updated first (the resourceVersion is the store's global write counter).

func (*Server) Login

Login implements gen.StrictServerInterface: a redirect to GitHub with a state bound to a short-lived cookie.

func (*Server) Logout

Logout implements gen.StrictServerInterface. It succeeds without a session too.

func (*Server) OpsHandler

func (s *Server) OpsHandler() http.Handler

OpsHandler serves /healthz, /readyz and /metrics. Serve it on a localhost listener only (`--ops-addr`): the routes have no auth.

func (*Server) PostCommand

PostCommand implements gen.StrictServerInterface (api-server.md §Commands). Commands about a work item become factory.command.* events on it; dispatch stores the injected event.

func (*Server) RegisterAgent

RegisterAgent implements gen.StrictServerInterface.

func (*Server) ReplayEvent

ReplayEvent implements gen.StrictServerInterface (api-server.md §Commands): the rule controller evaluates the stored event again with its own id and applies only the rules that didn't fire for it before; the response holds the decisions it recorded (each Replay).

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown ends the SSE streams and waits for them (or ctx). It also stops accepting leases: parked lease long polls answer 204 at once, and so does every later one. The caller shuts the http.Server down too.

func (*Server) StreamEvents

StreamEvents implements gen.StrictServerInterface: server-sent events from store watches. Each frame's id is the store version; with Last-Event-ID the watches replay from there (the store's history) and run progress is backfilled from the runs' ring buffers. A keep-alive comment is sent every KeepAlive; the stream ends when the client leaves or the server shuts down.

func (*Server) UpdateAgent

UpdateAgent implements gen.StrictServerInterface.

func (*Server) UploadEnvironmentLog

UploadEnvironmentLog implements gen.StrictServerInterface: the agent holding the run's lease stores its workspace's environment log (plain text, redacted by the agent) beside the transcript, under the transcripts' caps and retention, and the run records its reference.

func (*Server) UploadTranscript

UploadTranscript implements gen.StrictServerInterface.

type StoreReadiness added in v0.2.0

type StoreReadiness interface {
	Ready() error
}

StoreReadiness is a store that says whether it can serve: loaded, synced with the shared state within its maximum lag, and still writing (the object store). A store without it (memory, the file store) has nothing to sync: it is ready once it is loaded.

type StreamProgress

type StreamProgress struct {
	Run   string                 `json:"run"`
	Task  string                 `json:"task,omitempty"`
	Event v1alpha1.ProgressEvent `json:"event"`
}

StreamProgress is the data of a progress event.

Jump to

Keyboard shortcuts

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