sdk

package
v0.37.0 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package sdk is the typed Go client over the funcd control-plane REST API (ADR-0024). It speaks the code-first huma surface (ADR-0005/0018) at /apis/funcd.io/v1alpha1/..., exposing a kind-parameterized CRUD surface (Apply/Get/List/Delete) typed via the v1.Object interface — no generics, no `any`. It is on the public surface and depends only on api/** + stdlib.

Index

Constants

View Source 
const VoidSchema = `{"type":"null"}`

VoidSchema is the canonical void side (ADR-0090/0122): a contract side that carries no meaningful payload is the explicit JSON Schema {"type":"null"}, never an omission. Kept in pkg/sdk (not imported from internal/artifact) so funcdctl and the SDK share it without a package-boundary violation; the value matches internal/artifact.VoidSchema.

Variables

This section is empty.

Functions

func ContractName added in v0.15.0 

func ContractName(build string, isDir bool) string

ContractName is the name a build's contract file carries: a file's stem, or a bundle directory's base name (ADR-0247 Decision 2).

func DecodeManifest 

func DecodeManifest(data []byte) (v1.Object, error)

DecodeManifest parses a single-document resource manifest (apiVersion/kind/metadata/spec) into the concrete v1.Object. An unknown/empty kind is a fault.Invalid, never a panic; so is a manifest holding more than one document (DecodeManifests decodes each).

func DecodeManifests added in v0.2.1 

func DecodeManifests(data []byte) ([]v1.Object, error)

DecodeManifests parses a manifest that may hold several YAML documents separated by "---" into one v1.Object per document, in order. Empty and comment-only documents are skipped; a manifest with no document is a fault.Invalid.

func GenerateTypes 

func GenerateTypes(c *ContractFile, b v1.FunctionBindings) (map[string][]byte, error)

GenerateTypes returns funcd_types.py or funcd.d.ts for c's runtime family (ADR-0247 Decision 3, ADR-0122 Decision 4): the FuncInput/FuncOutput payload types from the contract file's sides, plus a typed binding context from b, the bindings of the Function document the contract file describes (empty for a step or an App part). python* ⇒ a ".py" module (top-level-importable, no TYPE_CHECKING dance); node* ⇒ a ".d.ts" (imported with `import type`). This is DX-only — the platform never trusts these types. The map is keyed by the file's basename; the caller writes each into the output directory.

func KindFromToken 

func KindFromToken(token string) (v1.Kind, bool)

KindFromToken resolves a CLI token (plural, singular, or alias) to a v1.Kind.

func ReadOnlyKind added in v0.6.0 

func ReadOnlyKind(k v1.Kind) bool

ReadOnlyKind reports whether the API serves only get and list for k, a kind a reconciler alone writes (ADR-0172, ADR-0200).

func ReadOnlyWriter added in v0.9.0 

func ReadOnlyWriter(k v1.Kind) string

ReadOnlyWriter names the writer of a read-only kind, for the refusal of a write to it; "" if k is writable.

Types

type ApplyOption added in v0.10.0 

type ApplyOption func(*applyOptions)

ApplyOption tunes an Apply.

func DryRun added in v0.10.0 

func DryRun() ApplyOption

DryRun makes Apply admit obj without storing it (ADR-0220): every request Apply sends carries dryRun=true, and the answer is the object as the write would store it, an App's with its plan in status.plan. Before its first dry-run write the client reads the server's OpenAPI document once; when the operation does not declare dryRun, Apply sends no write and fails, since an older server would ignore the flag and store the object.

type Client 

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

Client is a typed Go client over the funcd control-plane REST API.

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New builds a Client. baseURL (e.g. "http://localhost:8080") is required.

func (*Client) Apply 

func (c *Client) Apply(ctx context.Context, obj v1.Object, opts ...ApplyOption) (v1.Object, error)

Apply create-or-replaces obj: PUT the named path; on a 404 (the object does not yet exist) POST the collection path to create it. Returns the stored object, or with DryRun the object as it would be stored.

func (*Client) Create added in v0.2.1 

func (c *Client) Create(ctx context.Context, obj v1.Object) (v1.Object, error)

Create creates obj by POSTing the collection path, never replacing an existing object: a taken name is a fault.Conflict. An empty name with GenerateName set lets the server assign one.

func (*Client) DeadLetter 

func (c *Client) DeadLetter(ctx context.Context, ns v1.NamespaceName, id string) (deadletter.DeadLetter, error)

DeadLetter fetches one parked dead letter by id (ADR-0118), or fault.NotFound if absent.

func (*Client) DeadLetters 

func (c *Client) DeadLetters(ctx context.Context, ns v1.NamespaceName) ([]deadletter.DeadLetter, error)

DeadLetters lists a namespace's parked dead letters, newest first (ADR-0118). Tenant-scoped by the caller's identity (get/Sensor in the namespace) — the namespace is the authorized path segment.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, kind v1.Kind, ns v1.NamespaceName, name v1.ObjectName, opts ...DeleteOption) error

Delete removes one object.

func (*Client) DeleteVolume added in v0.24.0 

func (c *Client) DeleteVolume(ctx context.Context, ns v1.NamespaceName, fn, name v1.ObjectName) error

DeleteVolume removes a retained Function volume (ADR-0262 Decision 8): NotFound with none, Conflict while a live Function holds it.

func (*Client) DiscardDeadLetter 

func (c *Client) DiscardDeadLetter(ctx context.Context, ns v1.NamespaceName, id string) error

DiscardDeadLetter deletes a parked dead letter (ADR-0118) — a plain CRUD delete; absent is not an error server-side.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, kind v1.Kind, ns v1.NamespaceName, name v1.ObjectName) (v1.Object, error)

Get fetches one object.

func (*Client) HandoverKVStore added in v0.5.0 

func (c *Client) HandoverKVStore(ctx context.Context, ns v1.NamespaceName, store, workflow v1.ObjectName) error

HandoverKVStore makes workflow the owner of the kept KVStore store, so that Workflow binds it again (ADR-0178). The caller needs KVStore update and delete and Workflow get in ns.

func (*Client) HoldStatus added in v0.10.0 

func (c *Client) HoldStatus(ctx context.Context) (hold.Evidence, error)

HoldStatus reads the platform hold's evidence (ADR-0206 Decision 8); admin-only.

func (*Client) List 

func (c *Client) List(ctx context.Context, kind v1.Kind, ns v1.NamespaceName) ([]v1.Object, error)

List fetches every object of a kind in a namespace.

func (*Client) Logs 

func (c *Client) Logs(ctx context.Context, ns v1.NamespaceName, fn v1.ObjectName, o LogsOptions) ([]logread.Line, error)

Logs reads a function's logs from the control-plane logs route (ADR-0084). The result is tenant-scoped to the caller's authenticated identity by the server (admin sees any namespace, developer/viewer only a bound one) — the namespace is the authorized path segment, never a client-asserted filter.

func (*Client) PlatformBackup added in v0.10.0 

func (c *Client) PlatformBackup(ctx context.Context) (runner.Status, error)

PlatformBackup reads the platform backup's status (ADR-0205); only an admin may.

func (*Client) ReleaseHold added in v0.10.0 

func (c *Client) ReleaseHold(ctx context.Context, advance []string) error

ReleaseHold lifts the platform hold (ADR-0206 Decision 8). advance names blob EventSources, <ns>/<name>, whose listed keys are marked seen instead of replayed. Not held ⇒ fault.Conflict; an advance naming no blob event of an existing EventSource ⇒ fault.Invalid, both before any change.

func (*Client) ReleaseNamespaceHold added in v0.11.0 

func (c *Client) ReleaseNamespaceHold(ctx context.Context, namespaces []string) error

ReleaseNamespaceHold removes the hold a restore left on each namespace (ADR-0222 Decision 8): restore run's data marker and an ended in-place Restore's marker. POST …/hold/release with namespaces, which needs update on each Namespace; an in-place Restore still Pending or Running ⇒ fault.Conflict naming it.

func (*Client) ReplayDeadLetter 

func (c *Client) ReplayDeadLetter(ctx context.Context, ns v1.NamespaceName, id string) error

ReplayDeadLetter re-injects a parked dead letter through the LIVE Sensor action path (ADR-0118 §3): ONE synchronous attempt. Success removes the entry (nil); failure re-parks it (Attempts reset) and returns the delivery error; a gone Sensor/action ⇒ fault.NotFound.

func (*Client) RetryApp added in v0.10.0 

func (c *Client) RetryApp(ctx context.Context, ns v1.NamespaceName, name v1.ObjectName) error

RetryApp starts again, without waiting, the failed hook of the App's latest revision (ADR-0214 Decision 7). The caller needs App update in ns; fault.Conflict when the App has no failed hook, a hook call of it runs or it is paused.

func (*Client) ReturnQuarantined added in v0.30.0 

func (c *Client) ReturnQuarantined(ctx context.Context, r hold.QuarantineReturn) error

ReturnQuarantined returns an object's quarantined data into it (ADR-0288 Decision 6); admin-only. The object must exist and its data be empty (fault.Conflict otherwise); no such entry ⇒ fault.NotFound.

func (*Client) RunLogs 

func (c *Client) RunLogs(ctx context.Context, ns v1.NamespaceName, run v1.ObjectName, o LogsOptions) ([]logread.Line, error)

RunLogs reads a whole workflow run's logs from the run-scoped control-plane route (ADR-0106): the server resolves the run's status.traceId and returns the namespace-wide, trace-filtered lines — every step function's output plus any sub-workflow child steps (one composition = one trace). Tenant-scoped by the caller's identity (get/WorkflowRun in the namespace). o.Step narrows to one step's function.

type ContractFile added in v0.15.0 

type ContractFile struct {
	Runtime  v1.RuntimeName      `json:"runtime"`
	Protocol v1.FunctionProtocol `json:"protocol,omitempty"`
	Input    json.RawMessage     `json:"input,omitempty"`
	Output   json.RawMessage     `json:"output,omitempty"`
}

ContractFile is a function's contract file, <name>.contract.yaml or <name>.contract.json (ADR-0247 Decision 1): what its artifact is. The Function resource says how it runs.

func LoadContract added in v0.15.0 

func LoadContract(dir, name string) (*ContractFile, string, error)

LoadContract reads <dir>/<name>.contract.yaml or .json (exactly one), decodes it strictly, validates it (ADR-0247 Decision 1) and returns its path. A funcdctl.yaml where it looks fails, naming the files that replace it (Decision 11).

func (*ContractFile) Sides added in v0.15.0 

func (c *ContractFile) Sides() (input, output []byte)

Sides returns the two contract sides of a cloudevent Function, or none for an http one (ADR-0243).

type DeleteOption added in v0.4.0 

type DeleteOption func(*deleteOptions)

DeleteOption tunes a Delete.

func Force added in v0.4.0 

func Force() DeleteOption

Force deletes a ResourceGroup's members first, each under its own protections, then the group (ADR-0170). Delete refuses it with fault.Invalid for any other kind, before a request.

func IfVersion added in v0.10.0 

func IfVersion(rv string) DeleteOption

IfVersion makes Delete conditional on rv: fault.Conflict when the object's resourceVersion differs (ADR-0210).

type LogsOptions 

type LogsOptions struct {
	Since    string // logread.SinceForms: a duration ("15m") or a timestamp ("2026-10-07T22:00:00.000Z"); "" ⇒ no lower bound
	Severity string // minimum level (trace|debug|info|warn|error|fatal); "" ⇒ all
	Limit    int    // max records (most-recent); <= 0 ⇒ the server default
	Step     string // RunLogs only (ADR-0106): narrow to one step's function (the --step drill-down); "" ⇒ all
}

LogsOptions are the optional filters for Client.Logs / Client.RunLogs (ADR-0084/0106).

type ManifestDocument added in v0.2.2 

type ManifestDocument struct {
	Number int
	Object v1.Object
}

ManifestDocument is one decoded manifest document and its 1-based position in the manifest, counted as the decode errors count it (skipped empty and comment-only documents included).

func DecodeManifestDocuments added in v0.2.2 

func DecodeManifestDocuments(data []byte) ([]ManifestDocument, error)

DecodeManifestDocuments is DecodeManifests that also returns each object's document number, so a caller can name the document a later error belongs to (issue #316).

type Option 

type Option func(*Client)

Option configures a Client (functional-options facade, ADR-0002).

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient overrides the HTTP client (default http.DefaultClient). A client without a CheckRedirect policy gets the SDK's, which refuses a redirect that would change the method.

func WithToken 

func WithToken(token string) Option

WithToken sets the bearer token sent on every request (empty = unauthenticated).

Source Files

View all Source files

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.