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>
104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project
|
|
|
|
**PiCloud** is a self-hosted, event-driven serverless compute platform. Users upload Rhai scripts, get HTTP endpoints. Optimized for solo-dev / consumer hardware (single node MVP, multi-node cluster in v1.3+).
|
|
|
|
Authoritative design: [serverless_cloud_blueprint.md](serverless_cloud_blueprint.md). The blueprint is a living document — when architecture decisions are made in conversation that contradict it, treat the latest decision as truth and update the blueprint.
|
|
|
|
## Three-Service Architecture
|
|
|
|
The platform splits into three logical services, each backed by a `*-core` library crate so the same logic runs in single-process MVP mode and split-process cluster mode:
|
|
|
|
| Service | Role | Library crate |
|
|
|---------|------|---------------|
|
|
| **Manager** | Control plane: script CRUD, scheduling/cron, dashboard backend, config. Single-writer to Postgres. | `manager-core` |
|
|
| **Orchestrator** | Per-node ingress: receives HTTP (later SMTP, queue) events, resolves script, dispatches to local executor. Stateless. | `orchestrator-core` |
|
|
| **Executor** | Per-node compute: runs Rhai scripts in a sandboxed engine. Stateless. | `executor-core` |
|
|
|
|
In MVP, all three run in one process (`picloud` binary). In cluster mode, each runs as its own binary on each node, with one manager total and one orchestrator + executor per node.
|
|
|
|
**Key boundary:** the orchestrator never imports `executor-core` directly — it depends on an `ExecutorClient` trait. The local impl calls `executor-core` in-process; the remote impl is an HTTP client. Same pattern keeps cluster mode a swap, not a rewrite.
|
|
|
|
## Path Scheme
|
|
|
|
Versioned API surfaces live under `/api/v{N}/...`. See [docs/versioning.md](docs/versioning.md) for the full scheme.
|
|
|
|
- `/api/v1/admin/*` — manager (control plane: script CRUD, logs, config)
|
|
- `/api/v1/execute/{id}` — orchestrator (data plane: invoke a script by ID)
|
|
- `/exec/*` — orchestrator (data plane: invoke scripts at custom paths, v1.1+). Unversioned — the contract is user-defined per script.
|
|
- `/healthz` — liveness (string `"ok"`)
|
|
- `/version` — versions of every compatibility surface (JSON)
|
|
- `/` and static assets — dashboard (SvelteKit static build, served by Caddy)
|
|
|
|
Caddy fronts everything. Same Caddyfile shape works for single-node and cluster — only upstream targets change.
|
|
|
|
## Tech Stack
|
|
|
|
- **Rust 1.92+** workspace, pinned via `rust-toolchain.toml`
|
|
- **Axum** for HTTP, **Tokio** async, **sqlx** for Postgres
|
|
- **Rhai** embedded scripting (in `executor-core`)
|
|
- **PostgreSQL 15+** with `pgcrypto` and (v1.1+) `hstore`
|
|
- **SvelteKit** dashboard, static adapter, CodeMirror 6 for the script editor
|
|
- **Caddy 2** reverse proxy (auto-HTTPS in prod)
|
|
- **Docker Compose** for dev and single-node prod
|
|
|
|
## Common Commands
|
|
|
|
```sh
|
|
# Rust workspace
|
|
cargo check --workspace
|
|
cargo test --workspace
|
|
cargo fmt --all
|
|
cargo clippy --all-targets --all-features -- -D warnings
|
|
|
|
# Run the all-in-one binary (MVP entry point)
|
|
cargo run -p picloud
|
|
|
|
# Run a single test
|
|
cargo test -p executor-core sandbox::tests::respects_operation_budget
|
|
|
|
# Dashboard (from dashboard/)
|
|
npm run dev
|
|
npm run build
|
|
npm run check
|
|
|
|
# Full stack (once docker-compose.yml exists)
|
|
docker compose up
|
|
docker compose down -v # reset Postgres data
|
|
```
|
|
|
|
## Workspace Layout
|
|
|
|
```
|
|
crates/
|
|
shared/ # cross-cutting types (Script, IDs, error enum, db pool)
|
|
executor-core/ # Rhai engine, sandbox, ctx, log, SDK
|
|
orchestrator-core/ # event ingress + ExecutorClient trait + dispatch
|
|
manager-core/ # control plane: repos, scheduler, config
|
|
picloud/ # ★ MVP all-in-one binary
|
|
picloud-manager/ # cluster mode binary (skeleton)
|
|
picloud-orchestrator/ # cluster mode binary (skeleton)
|
|
picloud-executor/ # cluster mode binary (skeleton)
|
|
dashboard/ # SvelteKit
|
|
caddy/ # Caddyfile, Caddyfile.prod
|
|
docker/ # Dockerfiles
|
|
docs/
|
|
git-workflow.md # trunk-based workflow
|
|
architecture.md # (TBD)
|
|
```
|
|
|
|
## Working Rules
|
|
|
|
- **Honor the three-service boundary.** Don't reach across `*-core` crates. If `orchestrator-core` needs something from `manager-core`, define a trait in `shared` and inject the impl.
|
|
- **`executor-core` has no Postgres dependency.** Data-plane services (kv, docs, users — v1.1+) come in via injected `ServiceProvider` traits.
|
|
- **Database writes only from `manager-core`.** `orchestrator-core` reads scripts (cached); `executor-core` doesn't touch the DB.
|
|
- **MVP builds only the `picloud` all-in-one binary.** The three split binaries exist as skeletons so the crate boundaries stay honest; flesh them out only when cluster mode is being implemented.
|
|
- **Trunk-based dev.** See [docs/git-workflow.md](docs/git-workflow.md). No long-lived branches. Feature flags for incomplete work.
|
|
|
|
## Out of MVP
|
|
|
|
Queue triggers, cron triggers, SMTP ingress, KV / docs / email / users / HTTP SDKs in scripts, interceptors, workflows, function-to-function `invoke()`, auth, multi-tenancy, secrets, metrics dashboard. All deferred to v1.1+ per the blueprint. Don't pre-build for them — but don't make decisions that close the door on them either.
|