funcd

module

v0.2.0 Latest Latest Go to latest Published: Oct 2, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pyvvo/funcd

Links

Open Source Insights

README ¶

funcd

A lightweight, modular, single-binary serverless platform for Linux — faasd-like, Kubernetes-inspired internals, designed for the agent era.

blueprint.md — the platform blueprint: purpose, components, architecture, resource model, repository structure. The single architectural reference.
docs/feat/ — feature-version documents: the initial need and the high-level feature/component list per version (V1, V2, …). What and why — never how.
docs/adr/ — Architecture Decision Records. Every concrete decision (project setup, ports & drivers, gateway mechanics, …) is captured as an ADR: need, constraints, alternatives, final solution, and the contracts (interfaces, resource definitions, inputs/outputs) an implementer needs. Features are scaffolded and implemented from ADRs, gradually — no big-bang implementation.

Workflow

Each gate has a skill (.claude/skills/): plan → decide → judge → build → review.

Scope & sequence — docs/feat/ lists what a version must contain; the roadmap-planner skill sequences the ADRs into a computed delivery plan (docs/roadmap/: build waves, critical path).
Brainstorm a topic from that list with the adr skill (component, feature, cross-cutting concern).
ADR captures the decision and its contracts; mark it Proposed when ready.
Judge gate — the adr-judge skill reviews the ADR document against the blueprint, feat row, and related ADRs (inconsistency, bias, scope creep, strengths to keep); the human weighs the verdict and accepts. The feat row advances.
Scaffold — the adr-scaffold skill turns the ADR into a compiling skeleton: interfaces, facades, deps, one skipped test per scenario — no logic.
Review gate — the adr-impl-review skill runs the verification (build/lint/test, tree diff) against the ADR + Definition of Done, gives a severity-tiered verdict, and records a per-model quality scorecard (docs/reviews/).
Implement the feature; make the test skeletons pass.
Validate: full test suite green — every ADR scenario now passes.
Implementation review (recommended) — adr-impl-review again audits code + tests against the ADR and updates the model scorecard.

The current workflow (ADR-0000 gates 0–5)

#	Gate	Skill	Your model	Status moves it makes
0	Scope the version	`roadmap-planner`	—	(sequences ADRs; writes roadmap)
1–2	Brainstorm → Draft	adr	Opus 4.8 MAX	ADR `Draft → Proposed`; feat `idea → adr`
3	Judge gate (the ADR document)	adr-judge	Opus 4.8 Extra	none — it only reports; you then accept
—	Acceptance (human call)	—	you	ADR `→ Accepted`; blueprint + roadmap synced here; feat `→ accepted`
4	Implement (ADR + blueprint → working code)	adr-impl	Sonnet 4.6 medium	ADR `Accepted → Reviewing`; feat `→ reviewing`
5	Review gate (the code)	adr-impl-review	Opus 4.8 Extra	pass → ADR `Reviewing → Implemented`, feat `→ implemented`; else → report, advances nothing

The loop (exactly as you said): review changes-requested/fail → ADR stays Reviewing → back to gate 4 (adr-impl) to fix the model-attributed findings → re-review → repeat until the review gate passes and stamps Implemented. (adr-attributed findings don't loop here — they break out to a new superseding ADR.)

Repositories

funcd is split across the pyvvo org (ADR-0141):

Repo	Holds
pyvvo/funcd	the Go platform: daemon, API, CLI, SDK, runtime images, providers, e2e tests, ADRs
pyvvo/funcd-typescript	the Node shim and the TypeScript examples; npm `@funcd-dev/shim`
pyvvo/funcd-python	the Python shim and the Python examples; PyPI `funcd-shim`
pyvvo/funcd-functions	real functions deployed on the platform

funcd pins the two language repos as Go modules in go.mod, embeds their shims, and runs their committed examples in its e2e tests and Lima lanes. To take a new language release:

go get github.com/pyvvo/funcd-typescript@<tag>

To work on a shim and funcd together, clone the language repo next to funcd and add a local go.work, which git ignores:

go work init . ../funcd-typescript

Status

See docs/PROJECT-SUMMARY.md for what is built and the decision log.

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
fault Package fault is the shared error taxonomy for the funcd platform (ADR-0002).	Package fault is the shared error taxonomy for the funcd platform (ADR-0002).
lintfixture Package lintfixture holds a known-bad lint fixture for scenario: api-boundary-rule-fires (ADR-0027), gated behind the `lintfixture` build tag — see tests/lint-fixtures/lintrules_test.go.	Package lintfixture holds a known-bad lint fixture for scenario: api-boundary-rule-fires (ADR-0027), gated behind the `lintfixture` build tag — see tests/lint-fixtures/lintrules_test.go.
types/v1alpha1 Package v1alpha1 holds the v1alpha1 API types — shared between server, client, and SDK.	Package v1alpha1 holds the v1alpha1 API types — shared between server, client, and SDK.
cmd
funcd command Command funcd is the thin shell over the pkg/funcd platform library: it selects drivers and runs the platform until a signal arrives (ADR-0014).	Command funcd is the thin shell over the pkg/funcd platform library: it selects drivers and runs the platform until a signal arrives (ADR-0014).
funcdctl command Command funcdctl is a kubectl-style CLI over the funcd control-plane API (ADR-0024), built on the cobra command framework (ADR-0042).	Command funcdctl is a kubectl-style CLI over the funcd control-plane API (ADR-0024), built on the cobra command framework (ADR-0042).
docs
demo/server command Command demo-server starts an embedded funcd wired for real function execution, on fixed local ports, so a CLI demo (docs/demo/journey.sh) can drive `funcdctl` against it and invoke functions over HTTP.	Command demo-server starts an embedded funcd wired for real function execution, on fixed local ports, so a CLI demo (docs/demo/journey.sh) can drive `funcdctl` against it and invoke functions over HTTP.
internal
activator Package activator implements scale-to-zero (ADR-0016): an in-process data-path component backing a gateway route's upstream.	Package activator implements scale-to-zero (ADR-0016): an in-process data-path component backing a gateway route's upstream.
activator/storescaler Package storescaler is the V1 store-backed activator.Scaler driver (ADR-0016): it records a function's scale intent as its partitioned status Phase — the wake edge Idle→Deploying for replicas>=1, the reclaim edge *→Idle for replicas==0 — via store.Update.	Package storescaler is the V1 store-backed activator.Scaler driver (ADR-0016): it records a function's scale intent as its partitioned status Phase — the wake edge Idle→Deploying for replicas>=1, the reclaim edge *→Idle for replicas==0 — via store.Update.
artifact Package artifact is OCI artifact distribution (ADR-0031): how a function source bundle reaches the platform.	Package artifact is OCI artifact distribution (ADR-0031): how a function source bundle reaches the platform.
auth Package auth is the authorization kernel (ADR-0018): the Authorizer port (PDP) every enforcement point (PEP) calls, plus the typed principal/verb/decision model.	Package auth is the authorization kernel (ADR-0018): the Authorizer port (PDP) every enforcement point (PEP) calls, plus the typed principal/verb/decision model.
auth/authcontract Package authcontract is the shared conformance suite for the auth.Authorizer port (ADR-0018): Run asserts the default-deny namespace-RBAC guarantee against any driver — admin spans namespaces + cluster-scoped kinds, developer writes only in its namespaces, viewer is read-only, and an unknown principal is denied.	Package authcontract is the shared conformance suite for the auth.Authorizer port (ADR-0018): Run asserts the default-deny namespace-RBAC guarantee against any driver — admin spans namespaces + cluster-scoped kinds, developer writes only in its namespaces, viewer is read-only, and an unknown principal is denied.
auth/cedar Package cedar is the cedar-go authorization driver (ADR-0074) behind the auth.Authorizer port (ADR-0018): it answers per-object, fine-grained data-plane decisions (KV first) that the coarse RBAC driver cannot express.	Package cedar is the cedar-go authorization driver (ADR-0074) behind the auth.Authorizer port (ADR-0018): it answers per-object, fine-grained data-plane decisions (KV first) that the coarse RBAC driver cannot express.
auth/rbac Package rbac is the built-in namespace-scoped RBAC Authorizer driver (ADR-0018): admin / developer / viewer roles, default-deny.	Package rbac is the built-in namespace-scoped RBAC Authorizer driver (ADR-0018): admin / developer / viewer roles, default-deny.
blob Package blob is the storage-layer port (ADR-0007): opaque byte objects behind the blob.Bucket port.	Package blob is the storage-layer port (ADR-0007): opaque byte objects behind the blob.Bucket port.
blob/blobcontract Package blobcontract is the shared conformance suite for the blob.Bucket port (ADR-0007).	Package blobcontract is the shared conformance suite for the blob.Bucket port (ADR-0007).
blob/gocloud Package gocloud is the gocloud.dev/blob driver for the blob.Bucket port (ADR-0007): memory / file / S3 by URL, all pure-Go (no cgo).	Package gocloud is the gocloud.dev/blob driver for the blob.Bucket port (ADR-0007): memory / file / S3 by URL, all pure-Go (no cgo).
blob/s3gateway Package s3gateway is the funcd S3-protocol frontend over the blob.Bucket substrate (ADR-0080), with in-platform identity via funcd-managed per-function SigV4 keypairs resolved by an in-process versitygw auth.IAMService (ADR-0085).	Package s3gateway is the funcd S3-protocol frontend over the blob.Bucket substrate (ADR-0080), with in-platform identity via funcd-managed per-function SigV4 keypairs resolved by an in-process versitygw auth.IAMService (ADR-0085).
bus Package bus is the messaging port (ADR-0008): core pub/sub plus durable JetStream streams/consumers, behind the bus.Bus port.	Package bus is the messaging port (ADR-0008): core pub/sub plus durable JetStream streams/consumers, behind the bus.Bus port.
bus/buscontract Package buscontract is the shared conformance suite for the bus.Bus port (ADR-0008).	Package buscontract is the shared conformance suite for the bus.Bus port (ADR-0008).
bus/nats Package nats is the embedded-NATS driver for the bus.Bus port (ADR-0008): an in-process nats-server with JetStream (memory or file storage), all pure-Go (no cgo).	Package nats is the embedded-NATS driver for the bus.Bus port (ADR-0008): an in-process nats-server with JetStream (memory or file storage), all pure-Go (no cgo).
catalog/gateway Package gateway is the funcd catalog PEP proxy over the Quack/DuckLake serving path (ADR-0137, FEAT-0008/F102).	Package gateway is the funcd catalog PEP proxy over the Quack/DuckLake serving path (ADR-0137, FEAT-0008/F102).
contract Package contract enforces the funcd contract type profile (ADR-0058): the bounded, language-agnostic subset of JSON Schema 2020-12 that a function's I/O contract may use — "the def" (the discipline JTD and WIT apply).	Package contract enforces the funcd contract type profile (ADR-0058): the bounded, language-agnostic subset of JSON Schema 2020-12 that a function's I/O contract may use — "the def" (the discipline JTD and WIT apply).
controller Package controller is the one general reconcile engine (ADR-0015): a store-watch informer feeds a rate-limited, deduplicating workqueue that worker goroutines drain by calling each kind's registered Reconciler — with exponential-backoff retry, RequeueAfter, status write-back (the reconciler's), and clean shutdown.	Package controller is the one general reconcile engine (ADR-0015): a store-watch informer feeds a rate-limited, deduplicating workqueue that worker goroutines drain by calling each kind's registered Reconciler — with exponential-backoff retry, RequeueAfter, status write-back (the reconciler's), and clean shutdown.
controlplane Package controlplane owns the huma API registration, typed operations, the Handlers seam, and the api/fault → huma problem+json error bridge (ADR-0005).	Package controlplane owns the huma API registration, typed operations, the Handlers seam, and the api/fault → huma problem+json error bridge (ADR-0005).
controlplane/admission Package admission is the control-plane admission framework (ADR-0063): a two-phase pipeline (mutate-all → validate-all) of single-purpose Admissions run on every resource write, after authz and before the store.	Package admission is the control-plane admission framework (ADR-0063): a two-phase pipeline (mutate-all → validate-all) of single-purpose Admissions run on every resource write, after authz and before the store.
controlplane/cmd/specgen command Command specgen writes the huma-generated OpenAPI 3.1 spec to the committed path.	Command specgen writes the huma-generated OpenAPI 3.1 spec to the committed path.
controlplane/middleware Package middleware holds the control-plane API server's net/http middleware (ADR-0018).	Package middleware holds the control-plane API server's net/http middleware (ADR-0018).
dataplane Package dataplane is the function-invocation data plane (ADR-0033): the HTTP handler that serves function traffic, separate from the control-plane API (ADR-0028).	Package dataplane is the function-invocation data plane (ADR-0033): the HTTP handler that serves function traffic, separate from the control-plane API (ADR-0028).
edge/authn Package authn is the edge authentication PEP (ADR-0113, F77): for a data-plane request whose target has an `authenticated` stance, it extracts a bearer token, resolves it to a connection-scoped Identity (never client-asserted), and DELEGATES the allow/deny decision to the existing auth.Authorizer (RBAC namespace-scope in V1; fine-grained Cedar edge policy in V2).	Package authn is the edge authentication PEP (ADR-0113, F77): for a data-plane request whose target has an `authenticated` stance, it extracts a bearer token, resolves it to a connection-scoped Identity (never client-asserted), and DELEGATES the allow/deny decision to the existing auth.Authorizer (RBAC namespace-scope in V1; fine-grained Cedar edge policy in V2).
edge/limit Package limit is the ingress-protection middleware (ADR-0112, F75): it refuses abusive traffic on the data-plane chain BEFORE dataplane.Handler — and therefore before the activator can wake a scaled-to-zero sandbox (the reject returns without ever calling activator.ServeHTTP).	Package limit is the ingress-protection middleware (ADR-0112, F75): it refuses abusive traffic on the data-plane chain BEFORE dataplane.Handler — and therefore before the activator can wake a scaled-to-zero sandbox (the reject returns without ever calling activator.ServeHTTP).
edge/observ Package observ is the edge observability middleware (ADR-0114, F76): RED metrics (request rate / errors / duration by function+status) off the OTel meter, an edge span that mints or adopts a W3C traceparent so the downstream invocation span parents under it (the ingress hop joins the one-run-one-trace waterfall, ADR-0101/0102), and a structured access log correlated by X-Request-Id.	Package observ is the edge observability middleware (ADR-0114, F76): RED metrics (request rate / errors / duration by function+status) off the OTel meter, an edge span that mints or adopts a W3C traceparent so the downstream invocation span parents under it (the ingress hop joins the one-run-one-trace waterfall, ADR-0101/0102), and a structured access log correlated by X-Request-Id.
edge/router Package router is the edge request matcher (ADR-0110, F79): it compiles the Ready Route set into a host/path/method table and resolves a public data-plane request to a target (namespace, function).	Package router is the edge request matcher (ADR-0110, F79): it compiles the Ready Route set into a host/path/method table and resolves a public data-plane request to a target (namespace, function).
edge/shape Package shape is the edge shaping middleware (ADR-0114, F78): CORS (preflight + ACAO), response header inject/strip, and gzip compression that SKIPS streaming (text/event-stream) and upgrades (Connection: Upgrade / 101) and FORWARDS http.Flusher + http.Hijacker so SSE/WebSocket pass through unbroken.	Package shape is the edge shaping middleware (ADR-0114, F78): CORS (preflight + ACAO), response header inject/strip, and gzip compression that SKIPS streaming (text/event-stream) and upgrades (Connection: Upgrade / 101) and FORWARDS http.Flusher + http.Hijacker so SSE/WebSocket pass through unbroken.
edge/static Package static is the edge static-asset handler (ADR-0120, F82): it serves a Bucket-prefix static site directly through the FEAT-0006 edge — index resolution, content-types, a weak (ModTime,Size) ETag + conditional GET (304), HTTP Range (206), an optional SPA fallback, and a pinned three-tier Cache-Control — with no function code and no activator hop.	Package static is the edge static-asset handler (ADR-0120, F82): it serves a Bucket-prefix static site directly through the FEAT-0006 edge — index resolution, content-types, a weak (ModTime,Size) ETag + conditional GET (304), HTTP Range (206), an optional SPA fallback, and a pinned three-tier Cache-Control — with no function code and no activator hop.
edge/tls Package edgetls is the TLS termination provider port (ADR-0111, F74): it builds the *tls.Config funcd attaches to its own http.Servers (no listener handover — the caller drives ServeTLS).	Package edgetls is the TLS termination provider port (ADR-0111, F74): it builds the *tls.Config funcd attaches to its own http.Servers (no listener handover — the caller drives ServeTLS).
edge/tls/acme Package acme is the certmagic-backed ACME TLS driver (ADR-0111, F74): automatic public certificates via an ACME CA (Let's Encrypt by default; a test directory URL for Pebble).	Package acme is the certmagic-backed ACME TLS driver (ADR-0111, F74): automatic public certificates via an ACME CA (Let's Encrypt by default; a test directory URL for Pebble).