4c41374db4
Apps become the isolation boundary for scripts, routes, domains, and
later data. Doing this now — while the surface is small — avoids
several migrations on populated tables once v1.1 data-plane services
ship.
Schema (migration 0005_apps.sql):
- New tables: apps, app_domains (with shape_key UNIQUE for collision
detection), app_slug_history (for permanent slug-rename redirects).
- app_id added to scripts, routes, execution_logs (non-null, cascading
rules per row).
- Script-name uniqueness becomes per-app; the route unique index is
swapped for an app-scoped version.
- The "default" app is seeded unconditionally with a localhost claim;
existing scripts/routes backfill into it. Fresh installs additionally
get the Hello World seed via seed_hello_world_if_fresh after
migrations run (idempotent — only fires when the default app has no
scripts).
Orchestrator dispatch is two-phase: AppDomainTable resolves Host →
app_id (most-specific match wins, exact beats wildcard), then the
existing route matcher runs against that app's partitioned slice via
RouteTable. Unknown hosts return 404 at the app layer with a clear
message; /api/v1/execute/{id} still works as the implicit
__internal__ claim, decoupled from any public domain.
Manager API: full CRUD for /api/v1/admin/apps/* and
/api/v1/admin/apps/{id_or_slug}/domains/*, with slug:check + force
takeover semantics implementing the rename-history flow (two-step
check → confirm, never a single endpoint). Script create requires
app_id; list accepts ?app= filter. Route create validates host
against the parent app's claims; conflict detection stays strictly
intra-app.
Dashboard: /admin/apps and /admin/apps/{slug} (overview + scripts +
domains + settings tabs, with slug-history-aware redirects). Root
path redirects to the apps list. Script detail page gains an app
breadcrumb and threads app_id into the route preview.
Deferred per design: per-app admin roles. The require_admin middleware
remains the seam where role checks will slot in later.
Blueprint §11.5 and roadmap updated to reflect what shipped; docs/
versioning.md notes the schema 3 → 5 bump.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
114 lines
6.4 KiB
Markdown
114 lines
6.4 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.
|
|
|
|
**Current focus (Phase 4, v1.1):** data-plane SDKs — KV store, then document store, then HTTP client, then cron triggers. See blueprint §12. Phase 3 (admin auth + multi-app scoping) shipped; every v1.1+ table starts with `app_id UUID NOT NULL REFERENCES apps(id) ON DELETE CASCADE` and every Rhai SDK call resolves its app from the execution context.
|
|
|
|
## 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, routes CRUD + check + match, logs, config; apps CRUD once Phase 3b lands)
|
|
- `/api/v1/execute/{id}` — orchestrator (data plane: invoke a script by ID, always-available bypass)
|
|
- `/admin/*` — dashboard SPA (SvelteKit, `paths.base = '/admin'`)
|
|
- `/healthz` — liveness (string `"ok"`)
|
|
- `/version` — every compatibility-surface version + `public_base_url` (JSON)
|
|
- **everything else** — orchestrator's user-route matcher: user scripts bind to arbitrary paths via `POST /api/v1/admin/scripts/{id}/routes`; if no route matches, picloud returns 404 with a JSON error.
|
|
|
|
Reserved path prefixes (rejected at route creation): `/api/`, `/admin/`, `/healthz`, `/version`.
|
|
|
|
Caddy fronts everything. Same Caddyfile shape works for single-node and cluster — only upstream targets change.
|
|
|
|
**Param syntax convention:** route paths use `:name` (e.g., `/users/:id`); domains (once apps land) use `{name}` (e.g., `{tenant}.example.com`). These are deliberately distinct — never use `:` in a domain context or `{}` in a route-path context.
|
|
|
|
**Two-phase dispatch (Phase 3b onward):** the orchestrator first resolves `Host` → app (most-specific domain claim wins), then runs that app's route trie. The route matcher itself is unchanged and never sees other apps' routes.
|
|
|
|
## 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()`, 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.
|
|
|
|
**Pulled forward to Phase 3 (pre-v1.1):** admin auth, multi-app scoping. Cross-app data sharing (export/import) stays at v1.3+; the initial cut enforces strict isolation. See blueprint §11.5.
|