Help us shape the future of Go! Take the 2026 Go Developer Survey

api

package
v1.9.3 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package api provides HTTP handlers for the Dispatch API.

Package api provides HTTP handlers for the Dispatch API.

Package api provides HTTP handlers for the Dispatch API.

Package api provides HTTP handlers for the Dispatch API.

Package api provides request and response types for the Dispatch API.

Package api provides HTTP handlers for the Dispatch API.

Package api provides HTTP handlers for the Dispatch API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type API

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

API wires all Forge-style HTTP handlers together for the dispatch system.

func New

func New(eng *engine.Engine, router forge.Router, opts ...Option) *API

New creates an API from a dispatch Engine.

func (*API) Handler

func (a *API) Handler() http.Handler

Handler returns the fully assembled http.Handler with all routes. The routes are registered on the first call; later calls return the same handler. A route forge refuses is a programming error, so Handler panics with forge's reason rather than serve an api with a hole in it.

func (*API) RegisterRoutes

func (a *API) RegisterRoutes(router forge.Router) error

RegisterRoutes registers all dispatch API routes into the given Forge router with full OpenAPI metadata. It returns every route forge refused, each named by method and path. Forge refuses a handler it cannot bind, or a path that collides with one already registered, and that route would otherwise answer 404.

type CancelJobRequest

type CancelJobRequest struct {
	JobID string `path:"jobId" description:"Job ID"`
}

CancelJobRequest is the request for cancelling a job.

type CompleteDurableActivityRequest

type CompleteDurableActivityRequest operator.CompletionInput

type DLQCountResponse

type DLQCountResponse struct {
	Count int64 `json:"count"`
}

DLQCountResponse contains the DLQ entry count.

type DeleteCronRequest

type DeleteCronRequest struct {
	CronID string `path:"cronId" description:"Cron entry ID"`
}

DeleteCronRequest is the request for deleting a cron entry.

type DeleteDLQRequest

type DeleteDLQRequest struct {
	EntryID string `path:"entryId" description:"DLQ entry ID"`
}

DeleteDLQRequest is the request for deleting a DLQ entry.

type DisableCronRequest

type DisableCronRequest struct {
	CronID string `path:"cronId" description:"Cron entry ID"`
}

DisableCronRequest is the request for disabling a cron entry.

type EnableCronRequest

type EnableCronRequest struct {
	CronID string `path:"cronId" description:"Cron entry ID"`
}

EnableCronRequest is the request for enabling a cron entry.

type ErrorResponse

type ErrorResponse struct {
	Code  int    `json:"code"`
	Error string `json:"error"`
}

ErrorResponse is the body the router writes for an error. The operator routes declare it for 409 and 503, which WithErrorResponses leaves out.

type GetCronRequest

type GetCronRequest struct {
	CronID string `path:"cronId" description:"Cron entry ID"`
}

GetCronRequest is the request for fetching a single cron entry.

type GetDLQRequest

type GetDLQRequest struct {
	EntryID string `path:"entryId" description:"DLQ entry ID"`
}

GetDLQRequest is the request for fetching a single DLQ entry.

type GetJobRequest

type GetJobRequest struct {
	JobID string `path:"jobId" description:"Job ID"`
}

GetJobRequest is the request for fetching a single job.

type GetWorkflowRunRequest

type GetWorkflowRunRequest struct {
	RunID string `path:"runId" description:"Workflow run ID"`
}

GetWorkflowRunRequest is the request for fetching a single workflow run.

type HeartbeatDurableActivityRequest

type HeartbeatDurableActivityRequest operator.HeartbeatInput

type JobCountsResponse

type JobCountsResponse struct {
	Pending   int64 `json:"pending"`
	Running   int64 `json:"running"`
	Completed int64 `json:"completed"`
	Failed    int64 `json:"failed"`
	Retrying  int64 `json:"retrying"`
	Cancelled int64 `json:"cancelled"`
}

JobCountsResponse contains job counts by state.

type ListCronsRequest

type ListCronsRequest struct {
	Limit  int `query:"limit" optional:"true" description:"Maximum number of results (default: 50, max: 1000)"`
	Offset int `query:"offset" optional:"true" description:"Number of results to skip"`
}

ListCronsRequest is the request for listing cron entries. Both fields are optional query parameters.

type ListCronsResponse

type ListCronsResponse struct {
	Entries []*cron.Entry `body:""`
}

ListCronsResponse is a page of cron entries, oldest first, written as a bare JSON array.

type ListDLQRequest

type ListDLQRequest struct {
	Queue  string `query:"queue" optional:"true" description:"Filter by queue name"`
	Limit  int    `query:"limit" optional:"true" description:"Maximum number of results (default: 50, max: 1000)"`
	Offset int    `query:"offset" optional:"true" description:"Number of results to skip"`
}

ListDLQRequest is the request for listing DLQ entries. Every field is an optional query parameter.

type ListDLQResponse

type ListDLQResponse struct {
	Entries []*dlq.Entry `body:""`
}

ListDLQResponse is a page of DLQ entries, oldest failure first, written as a bare JSON array.

type ListJobsRequest

type ListJobsRequest struct {
	State  string `` /* 144-byte string literal not displayed */
	Queue  string `query:"queue" optional:"true" description:"Filter by queue name"`
	Limit  int    `query:"limit" optional:"true" description:"Maximum number of results (default: 50, max: 1000)"`
	Offset int    `query:"offset" optional:"true" description:"Number of results to skip"`
}

ListJobsRequest is the request for listing jobs. Every field is an optional query parameter.

type ListJobsResponse

type ListJobsResponse struct {
	Jobs []*job.Job `body:""`
}

ListJobsResponse is a page of jobs, oldest first. The body:"" tag has the router write Jobs as the whole body, a bare JSON array.

type ListWorkflowNamesResponse

type ListWorkflowNamesResponse struct {
	Names []string `json:"names"`
}

ListWorkflowNamesResponse contains the registered workflow names.

type ListWorkflowRunsRequest

type ListWorkflowRunsRequest struct {
	State  string `query:"state" optional:"true" description:"Filter by run state (running, completed, failed; default: every state)"`
	Limit  int    `query:"limit" optional:"true" description:"Maximum number of results (default: 50, max: 1000)"`
	Offset int    `query:"offset" optional:"true" description:"Number of results to skip"`
}

ListWorkflowRunsRequest is the request for listing workflow runs. Every field is an optional query parameter.

type ListWorkflowRunsResponse

type ListWorkflowRunsResponse struct {
	Runs []*workflow.Run `body:""`
}

ListWorkflowRunsResponse is a page of runs, oldest first, written as a bare JSON array.

type Option

type Option func(*API)

func WithDurableCallbacks

func WithDurableCallbacks(service *operator.Service, authenticator *security.ForgeAuthenticator) Option

WithDurableCallbacks mounts machine callback routes through the shared service. Supply the stock explicit-token ForgeAuthenticator configured with Authsome.

func WithSecurity

func WithSecurity(auth security.Authenticator, boundary security.Boundary) Option

WithSecurity supplies the verified HTTP identity and installation policy boundary.

type PlanWorkflowReplayRequest

type PlanWorkflowReplayRequest struct {
	RunID string `path:"runId" description:"Workflow run ID"`
	Step  string `query:"step" required:"true" description:"Checkpointed step to replay from"`
}

PlanWorkflowReplayRequest asks what replaying a run from a step would do.

type PurgeDLQRequest

type PurgeDLQRequest struct {
	Before    string `query:"before" optional:"true" description:"Purge entries that failed before this RFC 3339 time"`
	OlderThan string `query:"older_than" optional:"true" description:"Purge entries that failed longer ago than this Go duration, e.g. 72h"`
	DryRun    bool   `query:"dry_run" optional:"true" description:"Count the entries the cutoff matches without deleting any"`
}

PurgeDLQRequest sets the purge cutoff. Give before or older_than, not both; with neither the cutoff is 30 days ago. Query parameters, so a POST with no body still works.

type PurgeDLQResponse

type PurgeDLQResponse struct {
	Purged  int64     `json:"purged"`
	Matched int64     `json:"matched"`
	DryRun  bool      `json:"dry_run"`
	Before  time.Time `json:"before"`
}

PurgeDLQResponse reports a purge. Matched is how many entries failed before the cutoff; Purged is how many were deleted, zero on a dry run.

type ReplayAllDLQRequest

type ReplayAllDLQRequest struct {
	Queue string `query:"queue" optional:"true" description:"Replay only entries from this queue (default: every queue)"`
	Limit int    `query:"limit" optional:"true" description:"Maximum number of entries to try, 1 to 1000 (default: 1000)"`
}

ReplayAllDLQRequest selects the entries replay-all tries. Both fields are query parameters, so a POST with no body still works.

type ReplayAllDLQResponse

type ReplayAllDLQResponse struct {
	Replayed      int64    `json:"replayed"`
	Conflicts     int64    `json:"conflicts"`
	Errors        int64    `json:"errors"`
	ErrorMessages []string `json:"error_messages"`
}

ReplayAllDLQResponse counts what replay-all did with each entry it tried. Errors is the number that failed, as it always was.

type ReplayDLQRequest

type ReplayDLQRequest struct {
	EntryID string `path:"entryId" description:"DLQ entry ID"`
}

ReplayDLQRequest is the request for replaying a DLQ entry.

type ReplayWorkflowRequest

type ReplayWorkflowRequest struct {
	RunID string `path:"runId" description:"Workflow run ID"`
	Step  string `json:"step" description:"Checkpointed step to replay from; it and every step before it are kept"`
}

ReplayWorkflowRequest replays a finished run from a step.

type RetryJobRequest

type RetryJobRequest struct {
	JobID string `path:"jobId" description:"Job ID"`
}

RetryJobRequest is the request for retrying a failed job.

type StatsResponse

type StatsResponse struct {
	Jobs      JobCountsResponse `json:"jobs"`
	DLQCount  int64             `json:"dlq_count"`
	Workflows WorkflowCounts    `json:"workflows"`
}

StatsResponse contains aggregate dispatch statistics.

type TriggerCronRequest

type TriggerCronRequest struct {
	CronID string `path:"cronId" description:"Cron entry ID"`
}

TriggerCronRequest is the request for running a cron entry's job now.

type WorkflowCounts

type WorkflowCounts struct {
	Running   int `json:"running"`
	Completed int `json:"completed"`
	Failed    int `json:"failed"`
}

WorkflowCounts contains workflow run counts by state.

Jump to

Keyboard shortcuts

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