Documentation
¶
Overview ¶
General API metadata swag (`make swagger`) reads to generate the OpenAPI spec committed at api/agent/openapi.json — see that package's doc comment. Never hand-edit the generated spec; change the annotations on the handlers below (or here) and regenerate instead.
@title Patchcord Agent API @version 1 @description Public HTTP API for the Patchcord agent (vision document, section 10.1). Covers workflow triggering and run observability, connector CRUD and testing, application hosting, and a read-only plugin catalog listing; the rest of the vision document's API surface (actions, full plugin management) is not implemented yet. @description Every route marked with a lock icon below requires "Authorization: Bearer <admin token>" — but only once at least one admin token has been created (`patchcord auth token create`); a fresh agent answers every request unauthenticated, exactly as before this existed (ADR-0036). @BasePath /v1 @securityDefinitions.apikey BearerAuth @in header @name Authorization @description Admin token, if any has been created (see the top-level description). Pass as "Bearer <token>".
Package api exposes the agent's public HTTP API.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRouter ¶
NewRouter returns the agent's public HTTP API handler, wiring every route behind withAdminAuth (ADR-0036) except four deliberate exceptions: GET /v1/system/health (a liveness check has to answer before any caller could prove who it is), GET /v1/openapi.json (public API documentation, same convention as an authenticated API's docs page), GET /apps/{id}/ (serves an installed application's own static UI to whichever end user's browser loads it — that end user is never expected to hold an admin token), and GET /apps/ (an index of the same, opt-in via AppsDirectoryListingEnabled — see ADR-0061; it stays unauthenticated for the same reason /apps/{id}/ does, since it exposes nothing an end user couldn't already reach one /apps/{id}/ URL at a time). Three routes get their own dedicated wrapping instead: POST /v1/workflows/{id}/run and POST /v1/apps/{id}/sessions (see withRunAuth and handleCreateAppSession's doc comment), and POST /v1/webhooks/{id} (never admin-gated at all — see handleWebhookTrigger's doc comment, ADR-0037).
Types ¶
type ConnectorTester ¶
type ConnectorTester interface {
TestConnector(ctx context.Context, c *connectors.ResolvedConnector) (ok bool, message string, err error)
}
ConnectorTester attempts a live connection through the installed plugin that declares a resolved connector's type, returning whether it succeeded and a human-readable message — the HTTP counterpart to `patchcord connector test`. *plugins.Supervisor satisfies this by duck typing, the same pattern Deps.Executor already uses (ADR-0021), so this package never imports a concrete plugin process type.
type Deps ¶
type Deps struct {
DB *sql.DB
// Executor runs an action for a workflow step, typically
// internal/plugins.Supervisor (which satisfies runs.ActionExecutor by
// duck typing — ADR-0021). Only needed by handlers that trigger a run;
// left nil, POST /v1/workflows/{id}/run fails clearly rather than
// panicking.
Executor runs.ActionExecutor
// RunCtx is the base context a background-triggered run's runs.Continue
// call is derived from — never a request's own context, which is
// cancelled the moment the triggering HTTP response is written, long
// before the run itself finishes. Defaults to context.Background() when
// nil, so existing callers that build Deps{DB: db} directly keep
// working. The agent (internal/runtime) passes a context it cancels
// during its own shutdown sequence, so an in-flight background run is
// recorded Cancelled rather than left running against plugins that are
// about to be torn down.
RunCtx context.Context
// Logger receives background-run failures a triggering HTTP request has
// no way to report back (its response was already sent). Defaults to
// slog.Default() when nil.
Logger *slog.Logger
// Sessions issues and validates the limited sessions installed
// applications use (vision document, section 15.4). Only dereferenced
// when a request actually presents an "Authorization: Bearer" header
// that isn't a valid admin token (withRunAuth) or calls
// POST /apps/{id}/sessions — left nil, every other existing route keeps
// working exactly as before this
// package existed.
Sessions *auth.Store
// ConnectorTester attempts a live connection through a resolved
// connector's plugin, typically the same internal/plugins.Supervisor as
// Executor (it satisfies both by duck typing). Only needed by
// POST /connectors/{id}/test — left nil, that one endpoint fails clearly
// rather than panicking.
ConnectorTester ConnectorTester
// Secrets resolves connector and webhook trigger secret references.
// Defaults to secrets.EnvStore{} when nil, so existing callers that
// build Deps{DB: db} directly keep resolving "env" references exactly
// as before secrets.MultiStore existed (ADR-0040).
Secrets secrets.Store
// AppsDirectoryListingEnabled turns on GET /apps/, an Apache-style index
// page listing every installed application with a link to its
// /apps/{id}/. Defaults to false, so existing callers that build
// Deps{DB: db} directly keep the pre-ADR-0061 behavior: a plain 404.
AppsDirectoryListingEnabled bool
}
Deps holds the dependencies the public HTTP API needs to serve requests.
Source Files