api

package
v2.5.0 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package api is the thin driving adapter between the generated strict HTTP server (package apigen) and the engine. Every handler follows the same shape: convert the request, call exactly one engine method, convert the result or classify the error into a Problem-shaped response. No business logic lives here.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler 

func Handler(e *engine.Engine) http.Handler

Handler returns the complete net/http handler for the API, mounted under no particular prefix (the caller mounts it at /api/v1), with no PDF printer.

func New 

func New(e *engine.Engine, deps Deps) http.Handler

New returns the complete net/http handler for the API over the given engine and dependencies.

func ReportCSV added in v2.3.0 

func ReportCSV(t reporting.Table) ([]byte, error)

ReportCSV writes a report as CSV, a header row first.

Types

type AgentTokens added in v2.5.0 

type AgentTokens interface {
	Mint(ctx context.Context, label string, ttl time.Duration) (string, store.AgentGrant, error)
}

AgentTokens is the port POST /agents mints through: the authorization server that issues agents' tokens, which grants the signed-in person's agent and returns a token that carries the grant (docs/adr/0016).

type Deps 

type Deps struct {
	Printer printer.Printer
	// Authorizer answers GET /session's canWrite; the middleware still
	// decides every request. AllowAll when nil.
	Authorizer auth.Authorizer
	// Reports answers /reports. Nil turns reporting off: the reports
	// answer 404.
	Reports reporting.Reporter
	// AgentTokens mints the tokens POST /agents returns: the authorization
	// server's, when Cartograph is one. Nil answers 404.
	AgentTokens AgentTokens
}

Deps is what a Server needs beyond the engine.

type Server 

type Server struct {
	Engine  *engine.Engine
	Printer printer.Printer
	Authz   auth.Authorizer
	// Reports answers /reports; nil when the deployment turned
	// reporting off (docs/adr/0014).
	Reports reporting.Reporter
	// AgentTokens mints pasteable agent tokens; nil where another stack
	// authorizes agents.
	AgentTokens AgentTokens
}

Server implements apigen.StrictServerInterface over an *engine.Engine. Printer is the port a PDF goes through; nil means printer.None.

func (*Server) AcceptProposal added in v2.5.0 

func (s *Server) AcceptProposal(ctx context.Context, req apigen.AcceptProposalRequestObject) (apigen.AcceptProposalResponseObject, error)

AcceptProposal makes the record a proposal proposed, as the caller.

func (*Server) AppendSeriesItem added in v2.3.0 

func (s *Server) AppendSeriesItem(ctx context.Context, req apigen.AppendSeriesItemRequestObject) (apigen.AppendSeriesItemResponseObject, error)

AppendSeriesItem records one item of a series, such as a reading, and commits the manifest with it.

func (*Server) ApplyRef 

func (s *Server) ApplyRef(ctx context.Context, request apigen.ApplyRefRequestObject) (apigen.ApplyRefResponseObject, error)

ApplyRef includes one manifest, or many, in the live state. Many in one call, because one at a time was quadratic and felt it: the engine reloads and reindexes once for the batch.

func (*Server) CreateAgentToken added in v2.5.0 

func (s *Server) CreateAgentToken(ctx context.Context, req apigen.CreateAgentTokenRequestObject) (apigen.CreateAgentTokenResponseObject, error)

CreateAgentToken lets an agent act for the caller by a token they paste into its client.

func (*Server) DeclineProposal added in v2.5.0 

func (s *Server) DeclineProposal(ctx context.Context, req apigen.DeclineProposalRequestObject) (apigen.DeclineProposalResponseObject, error)

DeclineProposal declines a proposal, as the caller.

func (*Server) DeleteGoal 

func (s *Server) DeleteGoal(ctx context.Context, req apigen.DeleteGoalRequestObject) (apigen.DeleteGoalResponseObject, error)

func (*Server) DeleteManifest 

func (s *Server) DeleteManifest(ctx context.Context, req apigen.DeleteManifestRequestObject) (apigen.DeleteManifestResponseObject, error)

DeleteManifest excludes a manifest from the live state (any kind).

func (*Server) DiffManifest 

func (s *Server) DiffManifest(ctx context.Context, req apigen.DiffManifestRequestObject) (apigen.DiffManifestResponseObject, error)

func (*Server) DiscardWorking 

func (s *Server) DiscardWorking(ctx context.Context, req apigen.DiscardWorkingRequestObject) (apigen.DiscardWorkingResponseObject, error)

PutWorking saves a manifest's working copy without creating a version (autosave). DiscardWorking throws away a staged draft. Nothing is returned: the caller reads the manifest back, and what comes back is whatever the vault holds — the saved file, or nothing if it was never saved.

func (*Server) GetCharterPdf 

func (s *Server) GetCharterPdf(ctx context.Context, req apigen.GetCharterPdfRequestObject) (apigen.GetCharterPdfResponseObject, error)

GetCharterPdf prints the charter of a project, programme or operation to PDF. A project prints its working copy when asked, otherwise its latest version, and its working copy when it has no version yet: somebody exporting a draft wants the draft, not a refusal.

func (*Server) GetFlow 

func (s *Server) GetFlow(_ context.Context, req apigen.GetFlowRequestObject) (apigen.GetFlowResponseObject, error)

func (*Server) GetGapChecks 

func (s *Server) GetGapChecks(ctx context.Context, req apigen.GetGapChecksRequestObject) (apigen.GetGapChecksResponseObject, error)

GetProgrammeChecks mirrors the goal's shape rather than the project's: a flat list, no blocking count, because none of a programme's checks blocks anything.

func (*Server) GetGapCoverage 

func (s *Server) GetGapCoverage(ctx context.Context, req apigen.GetGapCoverageRequestObject) (apigen.GetGapCoverageResponseObject, error)

func (*Server) GetGoalChecks 

func (s *Server) GetGoalChecks(ctx context.Context, req apigen.GetGoalChecksRequestObject) (apigen.GetGoalChecksResponseObject, error)

func (*Server) GetGoalTree 

func (s *Server) GetGoalTree(ctx context.Context, _ apigen.GetGoalTreeRequestObject) (apigen.GetGoalTreeResponseObject, error)

func (*Server) GetHealth 

func (s *Server) GetHealth(_ context.Context, _ apigen.GetHealthRequestObject) (apigen.GetHealthResponseObject, error)

func (*Server) GetManifest 

func (s *Server) GetManifest(ctx context.Context, req apigen.GetManifestRequestObject) (apigen.GetManifestResponseObject, error)

func (*Server) GetOperationCharterHtml 

func (s *Server) GetOperationCharterHtml(
	ctx context.Context,
	req apigen.GetOperationCharterHtmlRequestObject,
) (apigen.GetOperationCharterHtmlResponseObject, error)

GetOperationCharterHtml renders an operation as its service description.

func (*Server) GetOperationChecks 

func (s *Server) GetOperationChecks(ctx context.Context, req apigen.GetOperationChecksRequestObject) (apigen.GetOperationChecksResponseObject, error)

GetOperationChecks: the same flat, advisory shape as a programme's.

func (*Server) GetPresenceDocument 

func (s *Server) GetPresenceDocument(ctx context.Context, _ apigen.GetPresenceDocumentRequestObject) (apigen.GetPresenceDocumentResponseObject, error)

GetPresenceDocument names the document that routes presence on screens not about one manifest.

func (*Server) GetProgrammeCharterHtml 

func (s *Server) GetProgrammeCharterHtml(
	ctx context.Context,
	req apigen.GetProgrammeCharterHtmlRequestObject,
) (apigen.GetProgrammeCharterHtmlResponseObject, error)

GetProgrammeCharterHtml renders a programme as a document.

func (*Server) GetProgrammeChecks 

func (s *Server) GetProgrammeChecks(ctx context.Context, req apigen.GetProgrammeChecksRequestObject) (apigen.GetProgrammeChecksResponseObject, error)

func (*Server) GetProjectCharterHtml 

func (s *Server) GetProjectCharterHtml(ctx context.Context, req apigen.GetProjectCharterHtmlRequestObject) (apigen.GetProjectCharterHtmlResponseObject, error)

func (*Server) GetProjectChecks 

func (s *Server) GetProjectChecks(ctx context.Context, req apigen.GetProjectChecksRequestObject) (apigen.GetProjectChecksResponseObject, error)

func (*Server) GetProjectState 

func (s *Server) GetProjectState(ctx context.Context, req apigen.GetProjectStateRequestObject) (apigen.GetProjectStateResponseObject, error)

func (*Server) GetReferences 

func (s *Server) GetReferences(ctx context.Context, req apigen.GetReferencesRequestObject) (apigen.GetReferencesResponseObject, error)

func (*Server) GetReport added in v2.3.0 

func (s *Server) GetReport(ctx context.Context, req apigen.GetReportRequestObject) (apigen.GetReportResponseObject, error)

GetReport answers a report from the deployment's reporter, as JSON or as CSV; 404 when reporting is off.

func (*Server) GetSchema 

func (s *Server) GetSchema(_ context.Context, req apigen.GetSchemaRequestObject) (apigen.GetSchemaResponseObject, error)

func (*Server) GetSession 

func (s *Server) GetSession(ctx context.Context, _ apigen.GetSessionRequestObject) (apigen.GetSessionResponseObject, error)

GetSession says who this request acts as. canWrite is the authorizer's answer for a write with no particular manifest; the engine still decides every write on its own.

func (*Server) GetSettings 

func (s *Server) GetSettings(ctx context.Context, _ apigen.GetSettingsRequestObject) (apigen.GetSettingsResponseObject, error)

func (*Server) GetSharedDocument 

func (s *Server) GetSharedDocument(ctx context.Context, req apigen.GetSharedDocumentRequestObject) (apigen.GetSharedDocumentResponseObject, error)

GetSharedDocument names a manifest's shared draft, creating it on first use (docs/adr/0007).

func (*Server) GetVault 

func (s *Server) GetVault(ctx context.Context, _ apigen.GetVaultRequestObject) (apigen.GetVaultResponseObject, error)

GetVault returns the state manifest: what the live state includes.

func (*Server) GetVersion 

func (s *Server) GetVersion(ctx context.Context, req apigen.GetVersionRequestObject) (apigen.GetVersionResponseObject, error)

func (*Server) GetWorking 

func (s *Server) GetWorking(ctx context.Context, req apigen.GetWorkingRequestObject) (apigen.GetWorkingResponseObject, error)

GetWorking returns the working copy as last saved, decoded through the engine's codec, or 404 when the manifest has none.

func (*Server) GrantPerson added in v2.2.0 

func (s *Server) GrantPerson(ctx context.Context, req apigen.GrantPersonRequestObject) (apigen.GrantPersonResponseObject, error)

func (*Server) ListAgentGrants added in v2.5.0 

func (s *Server) ListAgentGrants(ctx context.Context, req apigen.ListAgentGrantsRequestObject) (apigen.ListAgentGrantsResponseObject, error)

ListAgentGrants lists the agents people let act for them.

func (*Server) ListExcluded 

func (s *Server) ListExcluded(ctx context.Context, _ apigen.ListExcludedRequestObject) (apigen.ListExcludedResponseObject, error)

ListExcluded lists every excluded manifest, newest first.

func (*Server) ListFlows 

func (s *Server) ListFlows(context.Context, apigen.ListFlowsRequestObject) (apigen.ListFlowsResponseObject, error)

func (*Server) ListKinds 

func (s *Server) ListKinds(_ context.Context, _ apigen.ListKindsRequestObject) (apigen.ListKindsResponseObject, error)

func (*Server) ListManifests 

func (s *Server) ListManifests(ctx context.Context, req apigen.ListManifestsRequestObject) (apigen.ListManifestsResponseObject, error)

func (*Server) ListPeople added in v2.2.0 

func (s *Server) ListPeople(ctx context.Context, _ apigen.ListPeopleRequestObject) (apigen.ListPeopleResponseObject, error)

func (*Server) ListProposals added in v2.5.0 

func (s *Server) ListProposals(ctx context.Context, req apigen.ListProposalsRequestObject) (apigen.ListProposalsResponseObject, error)

ListProposals lists what agents proposed (docs/adr/0016): the caller's open ones by default, or every proposal on one manifest.

func (*Server) ListSnapshots 

func (s *Server) ListSnapshots(ctx context.Context, req apigen.ListSnapshotsRequestObject) (apigen.ListSnapshotsResponseObject, error)

ListSnapshots returns every snapshot (version) across all kinds, newest first.

func (*Server) ListUnapplied 

func (s *Server) ListUnapplied(ctx context.Context, _ apigen.ListUnappliedRequestObject) (apigen.ListUnappliedResponseObject, error)

ListUnapplied lists manifests present but not in the live state.

func (*Server) ListVersions 

func (s *Server) ListVersions(ctx context.Context, req apigen.ListVersionsRequestObject) (apigen.ListVersionsResponseObject, error)

func (*Server) PostSnapshot 

func (s *Server) PostSnapshot(ctx context.Context, req apigen.PostSnapshotRequestObject) (apigen.PostSnapshotResponseObject, error)

PostSnapshot records an explicit version of a manifest's current content with a reason. Snapshots the working copy if one exists, otherwise the current version. The author is from Settings.spec.operator.

func (*Server) PutManifest 

func (s *Server) PutManifest(ctx context.Context, req apigen.PutManifestRequestObject) (apigen.PutManifestResponseObject, error)

func (*Server) PutWorking 

func (s *Server) PutWorking(ctx context.Context, req apigen.PutWorkingRequestObject) (apigen.PutWorkingResponseObject, error)

func (*Server) RecoverRef 

func (s *Server) RecoverRef(ctx context.Context, request apigen.RecoverRefRequestObject) (apigen.RecoverRefResponseObject, error)

RecoverRef re-includes an excluded manifest in the live state.

func (*Server) RemovePerson added in v2.2.0 

func (s *Server) RemovePerson(ctx context.Context, req apigen.RemovePersonRequestObject) (apigen.RemovePersonResponseObject, error)

func (*Server) RevokeAgentGrant added in v2.5.0 

func (s *Server) RevokeAgentGrant(ctx context.Context, req apigen.RevokeAgentGrantRequestObject) (apigen.RevokeAgentGrantResponseObject, error)

RevokeAgentGrant disconnects an agent at once.

func (*Server) Sync 

func (s *Server) Sync(_ context.Context, _ apigen.SyncRequestObject) (apigen.SyncResponseObject, error)

Sync answers a request to the sync path that did not upgrade: the socket itself is served by the sync server, mounted ahead of this handler (cmd/cartograph).

func (*Server) TransitionProjectState 

func (s *Server) TransitionProjectState(ctx context.Context, req apigen.TransitionProjectStateRequestObject) (apigen.TransitionProjectStateResponseObject, error)

func (*Server) ValidateManifest 

func (s *Server) ValidateManifest(ctx context.Context, req apigen.ValidateManifestRequestObject) (apigen.ValidateManifestResponseObject, error)

Source Files

View all Source files

Directories

Path Synopsis
Package apigen provides primitives to interact with the openapi HTTP API.
 Package apigen provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.