Documentation
¶
Overview ¶
Package rest integrates an external HTTP-REST API as a service-task connector: a BPMN REST connector task calls a model-authored endpoint through the job path (ADR-0036/0067), mirroring how the dmn package delegates a decision to temis (ADR-0014). The integration inherits the job protocol's durability and non-blocking properties (ADR-0007):
- A connector task creates a job carrying the reserved compiler.RestJobType. The processor never performs the outbound call itself, so it stays allocation-free (invariant I1) and free of any HTTP dependency.
- The in-process Handler — a job worker — pulls those jobs, calls the REST API off the processor goroutine and after fsync (invariant I2, never inside applyToState / I4), writes the JSON response into the task's result variable, and completes the job, which drives the token onward.
Unlike the clio connector (ADR-0036), a REST task authors its full URL, method, headers, and query parameters in the model; credentials are never authored there — authentication (basic/bearer/apiKey) names a server-side secret the worker resolves at runtime (ADR-0041/0067), so a token never appears in a BPMN file.
Delivery is at-least-once (a crash between "the API accepted the call" and "job completed" replays the request); every request carries the job key as an Idempotency-Key header so a well-behaved API de-duplicates a replayed non-idempotent request rather than performing it twice.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(store *state.Store, lookup ProcessLookup, client Client, secret SecretResolver) job.OutputHandler
Handler builds a job handler that performs an HTTP-REST connector task. Register it with a job.Runner under the reserved compiler.RestJobTypeIndex via HandleWithOutput; the runner then pulls activatable REST jobs, and for each the handler resolves the connector task's method/url/headers/query/result-variable from the compiled process and calls the API through client — evaluating any FEEL url/header/query values over the instance's variables (the fx toggle, ADR-0067) and sending the instance's variables as the JSON request body for methods that carry one, keyed by the job key so an at-least-once retry de-duplicates. Authentication (basic/bearer/apiKey) is resolved through secret, which turns the model's secret *reference* into the credential at call time (ADR-0041); the token never lives in the model. When the task names a result variable, the JSON response is returned as that variable to be written back into the instance on completion. Returning an error fails the job (retry, then an incident, ADR-0061); the runner completes it only on success.
Types ¶
type Client ¶
Client calls a REST API. It is an interface so the worker is testable without a live server.
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient calls a real REST API over HTTP. It sends Request.Body as a JSON body (when present) to Request.URL with an Idempotency-Key header, and decodes a JSON response body. A non-2xx status is returned as an error so the job stays pending and is retried (at-least-once).
func NewHTTPClient ¶
func NewHTTPClient() *HTTPClient
NewHTTPClient builds a REST HTTP client backed by http.DefaultClient. A configurable timeout is a follow-up (ADR-0067).
type ProcessLookup ¶
type ProcessLookup func(defKey uint64) *compiler.CompiledProcess
ProcessLookup resolves a process-definition key to its compiled process. The worker uses it to find the method, URL, and result variable a REST job belongs to, so one handler serves every deployed process.
type Request ¶
type Request struct {
Method string
URL string
Headers map[string]string
Query map[string]string
Body map[string]any
IdempotencyKey string
}
Request is one HTTP call a REST connector task makes. URL is the full, model-authored endpoint (ADR-0067). Headers are set on the request (including any Authorization/api-key header the worker resolved from a secret); Query is appended to the URL. Body, when non-nil, is sent as a JSON request body (the worker attaches it only for methods that carry one). IdempotencyKey is deterministic (the job key), so an at-least-once retry can be de-duplicated by the target API.
type Response ¶
Response is a REST call's outcome. Status is the HTTP status code; Body is the decoded JSON response (an object, array, number, string, bool or nil), or the raw response text when it is not valid JSON.
type SecretResolver ¶
SecretResolver returns the secret value for a reference name, or "" if unknown. The worker uses it to turn a REST task's authentication secret *reference* into the actual credential at call time (ADR-0041), so a token never lives in the model or the compiled process — only its reference does.
Source Files