0473d295af
Establish how versions are assigned, bumped, and checked across the
five things that actually change for users: the product itself, the
Rhai SDK, the HTTP API, the database schema, and the inter-service
wire (reserved for cluster mode). Crates ship in lockstep — drift
between picloud-shared and picloud-manager-core is fiction since
they always release together — but surfaces are versioned and
checked at their natural boundaries.
* docs/versioning.md is the authoritative reference: what gets a
version, the per-surface compatibility rules, how each surface
bump cascades to the product version (loose pre-1.0, strict
post-1.0), and the five enforcement mechanisms (lockstep at
compile time, /version at runtime, golden SDK contract tests,
migration replay, CI guardrail).
* shared::version exposes four constants — PRODUCT_VERSION (from
CARGO_PKG_VERSION), SDK_VERSION ("1.0"), API_VERSION (1),
WIRE_VERSION (1). Scripts read SDK_VERSION as ctx.sdk_version
and can feature-detect against it.
* Workspace inheritance: `[workspace.package] version = "0.2.0"`
is the single point of truth; every crate uses
`version.workspace = true`. dashboard/package.json mirrors.
* Routes move to /api/v1/* — both control plane
(/api/v1/admin/*) and data plane (/api/v1/execute/{id}).
Picloud composes them via a single `/api/v{API_VERSION}` nest,
so the next major is a copy-paste-and-bump. Caddyfile (dev and
prod) routes /api/v1/* to picloud and 404s any other /api/*
so old clients fail loudly instead of getting the SPA shell.
Dashboard client + integration tests updated.
* /healthz remains a plain "ok" string (k8s probes); /version is
the new JSON endpoint returning every surface version in one
place — product, sdk, api, schema (from
manager-core::migrations::latest_version), wire.
* Reasonable bump rationale: API path changes are breaking by
definition, so 0.1.0 → 0.2.0 (pre-1.0 license to bump minor on
any breaking change). SDK starts at 1.0 because scripts depend
on it more strictly than the product depends on its internals;
we'd rather promise SDK stability early than pull the rug.
Verified live:
* /healthz → "ok" (plain text)
* /version → {product:"0.2.0",sdk:"1.0",api:1,schema:1,wire:1}
* /api/v1/admin/scripts → 200
* /api/admin/scripts → 404 with error JSON (sunset major)
* Script can read ctx.sdk_version → "1.0"
* All 14 integration tests pass against new paths
* 11 executor-core unit tests pass (added one for sdk_version
exposure with the major.minor format invariant)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
72 lines
1.8 KiB
Caddyfile
72 lines
1.8 KiB
Caddyfile
# PiCloud dev Caddyfile.
|
|
#
|
|
# Same routing shape as prod, with two differences:
|
|
# - bound to plain HTTP (no domain, no automatic TLS)
|
|
# - upstreams are the docker-compose service names
|
|
#
|
|
# Control plane (`/api/admin/*`) and data plane (`/api/execute/*`, `/exec/*`)
|
|
# both terminate on the `picloud` all-in-one for now; in cluster mode the
|
|
# data-plane handles will list multiple orchestrator upstreams here while
|
|
# the admin handle still points at a single manager.
|
|
{
|
|
auto_https off
|
|
admin off
|
|
log {
|
|
output stdout
|
|
format console
|
|
}
|
|
}
|
|
|
|
:80 {
|
|
# Health + version are unversioned (k8s probes, monitoring).
|
|
handle /healthz {
|
|
reverse_proxy picloud:8080
|
|
}
|
|
handle /version {
|
|
reverse_proxy picloud:8080
|
|
}
|
|
|
|
# Versioned API (see docs/versioning.md). When v2 ships, add a
|
|
# second `handle /api/v2/...` block while keeping v1 live for at
|
|
# least one product-minor deprecation window.
|
|
|
|
# Control plane → manager (single-process: picloud).
|
|
handle /api/v1/admin/* {
|
|
reverse_proxy picloud:8080
|
|
}
|
|
|
|
# Data plane → orchestrator (single-process: picloud).
|
|
handle /api/v1/execute/* {
|
|
reverse_proxy picloud:8080
|
|
}
|
|
|
|
# Unversioned: user-defined script paths (v1.1+). Contract is just
|
|
# "your script runs against this body", so no API versioning applies.
|
|
handle /exec/* {
|
|
reverse_proxy picloud:8080
|
|
}
|
|
|
|
# Anything else under /api/* — old major versions that have been
|
|
# fully sunset, or typos. Fail loudly rather than silently serving
|
|
# the dashboard SPA.
|
|
handle /api/* {
|
|
respond 404 {
|
|
body "{\"error\":\"no such API version — see /version for supported routes\"}"
|
|
close
|
|
}
|
|
}
|
|
|
|
# Everything else → dashboard SPA (Caddy serves a self-contained
|
|
# dashboard container that already runs file_server with index.html
|
|
# fallback for client-side routing).
|
|
handle {
|
|
reverse_proxy dashboard:80
|
|
}
|
|
|
|
log {
|
|
output stdout
|
|
format console
|
|
}
|
|
}
|