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

sdk

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 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) 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) 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.