feat: custom routing — bind scripts to your own URLs

Scripts can now answer at user-chosen paths (e.g. /greet, /greet/:name,
/webhooks/*), on user-chosen hosts (strict or *.example.com wildcards),
on user-chosen methods. The internal /api/v1/execute/{id} endpoint
stays as the always-available ID-based bypass.

Routing rules (decided in design with the user; see chat history):

  Path kinds:
    exact   /greet              literal
    prefix  /greet/*            strict-subtree; stored as "/greet/";
                                does NOT match bare /greet (add an
                                exact route for that case)
    param   /users/:id          :name captures one whole segment;
                                mid-segment colons are rejected;
                                {name} is reserved for a future SDK

  Host kinds:
    any                         no Host header constraint
    strict  sub.example.com     literal match (case-insensitive)
    wildcard *.example.com      suffix match; multi-level subdomains OK

  Within-kind uniqueness:
    two routes of the same kind that could match the same request
    conflict at config time. Algorithm (orchestrator_core::routing::
    conflict):
      exact:  literal equality
      prefix: literal equality (longer-prefix coexists; longer wins
              at request time)
      param:  same segment count + same literals at every
              literal-vs-literal position (the user's example:
              :id vs :userId at same shape is a conflict)

  Request-time precedence:
    exact > param > prefix
    among non-exact: more leading-literal segments wins
    tie: param > prefix (more constrained)
    within prefix: longest matching prefix wins
    host bucket: strict > wildcard (longer suffix) > any; fall through
    to less specific buckets when path doesn't match

  Reserved path prefixes: /api/, /admin/, /healthz, /version

  Routes that look invalid at config time return 422 with the precise
  parse error; conflicting routes return 409 with the conflicting route
  in the body (so the dashboard can render the conflict inline).

What landed:

  * 0003_routes.sql — routes table (host_kind, host, host_param_name,
    path_kind, path, method, script_id) with UNIQUE index on the
    literal binding tuple. Schema 2 → 3.

  * shared::Route / HostKind / PathKind — flat storage shape that
    crosses wire boundaries cleanly.

  * orchestrator_core::routing — four sub-modules, all unit-tested:
      pattern.rs (16 tests)  parse + validate + display
      conflict.rs (12 tests) within-kind overlap predicate
      matcher.rs (12 tests)  runtime dispatch (specificity-aware)
      table.rs               Arc<RwLock<Vec<CompiledRoute>>>
                             shared by manager (writes) and
                             orchestrator (reads); atomic replace
                             after each admin write

  * manager-core::route_admin — five new admin endpoints under
    /api/v1/admin:
      POST   /scripts/{id}/routes      create
      GET    /scripts/{id}/routes      list per script
      DELETE /routes/{route_id}        delete (refreshes table)
      POST   /routes:check             pre-flight conflict check
                                       (powers the dashboard's
                                       live conflict warning)
      POST   /routes:match             synthetic URL → matched
                                       route + extracted params
                                       (powers the dashboard's
                                       match-preview tool)
    Stored path strings stay raw (user-typed); normalization
    happens only in the in-memory CompiledRoute so re-parses are
    idempotent.

  * orchestrator_core::api::user_routes_router — fallback handler
    mounted in picloud after the system routes. Reads Host /
    method / path / query from the request, dispatches via the
    table, builds an ExecRequest with params/query/rest filled,
    calls the executor, writes to the log sink. 10 MiB body cap.

  * executor-core::ctx (SDK 1.0 → 1.1) — adds
      ctx.request.params  (map of named-param captures)
      ctx.request.query   (parsed query string)
      ctx.request.rest    (suffix for prefix routes; "" otherwise)
    All three are always present (empty when not applicable) so
    scripts can read them unconditionally.

  * picloud::build_app — now async; loads routes at startup,
    populates the shared table, mounts route_admin_router under
    /api/v1/admin alongside the script CRUD, and the user-routes
    fallback at the app root.

  * caddy/Caddyfile + Caddyfile.prod widened: anything not
    /healthz, /version, /api/v1/admin/*, /api/v1/execute/*,
    /api/* (404 sunset), or /admin/* (dashboard) → picloud.

  * Dashboard moves to /admin/* via SvelteKit paths.base. Its
    internal Caddy strips the prefix and serves with SPA fallback.
    All in-app links use $app/paths. The dashboard URL is now
    http://localhost:8000/admin/ — one-time break for the new
    URL freedom users gained.

  * PICLOUD_PUBLIC_BASE_URL env var, exposed via /version so the
    dashboard renders full URLs for routes regardless of the
    operator's external port / TLS setup.

  * memory_limit_mb stays in the schema, still v1.3+ advisory.

Verified live through Caddy:
  /version              → schema 3, sdk 1.1, public_base_url
  GET /admin/           → 200, dashboard HTML containing "PiCloud"
  POST /api/v1/admin/scripts → 201
  POST .../scripts/{id}/routes (path=/greet/:name) → 201
  GET /greet/alice?lang=en → 200 {"name":"alice","q":"en"}
  POST conflicting route → 409 with conflicting_route body
  POST /admin/foo route → 422 "reserved"
  POST /api/v1/admin/routes:match → matched + params extracted
  GET /unbound-path → 404 JSON

Tests:
  * 40 routing unit tests (pattern + conflict + matcher tables)
  * 14 executor-core unit tests (one new for ctx.request.params/
    query/rest exposure)
  * 32 integration tests (10 new for routing CRUD + dispatch +
    conflict + reserved + specificity tie-break + match preview +
    delete invalidation + /version returns public_base_url)
  * default cargo test --workspace stays green; opt-in via
    DATABASE_URL + --include-ignored for the integration suite

Bumps: schema 2 → 3; SDK 1.0 → 1.1; product 0.3.0 → 0.4.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/manager-core/src/route_repo.rs

@@ -0,0 +1,168 @@
+//! CRUD over the `routes` table.
+//!
+//! The orchestrator's `RouteTable` is repopulated from this repo after
+//! every write — see the route_admin module for the binding.
+
+use async_trait::async_trait;
+use picloud_shared::{HostKind, PathKind, Route, ScriptId};
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use crate::repo::ScriptRepositoryError;
+
+#[derive(Debug, Clone)]
+pub struct NewRoute {
+    pub script_id: ScriptId,
+    pub host_kind: HostKind,
+    pub host: String,
+    pub host_param_name: Option<String>,
+    pub path_kind: PathKind,
+    pub path: String,
+    pub method: Option<String>,
+}
+
+#[async_trait]
+pub trait RouteRepository: Send + Sync {
+    async fn list_all(&self) -> Result<Vec<Route>, ScriptRepositoryError>;
+    async fn list_for_script(
+        &self,
+        script_id: ScriptId,
+    ) -> Result<Vec<Route>, ScriptRepositoryError>;
+    async fn create(&self, input: NewRoute) -> Result<Route, ScriptRepositoryError>;
+    async fn delete(&self, route_id: Uuid) -> Result<(), ScriptRepositoryError>;
+}
+
+pub struct PostgresRouteRepository {
+    pool: PgPool,
+}
+
+impl PostgresRouteRepository {
+    #[must_use]
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+}
+
+#[async_trait]
+impl RouteRepository for PostgresRouteRepository {
+    async fn list_all(&self) -> Result<Vec<Route>, ScriptRepositoryError> {
+        let rows = sqlx::query_as::<_, RouteRow>(
+            "SELECT id, script_id, host_kind, host, host_param_name, \
+                    path_kind, path, method, created_at \
+             FROM routes ORDER BY created_at",
+        )
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    async fn list_for_script(
+        &self,
+        script_id: ScriptId,
+    ) -> Result<Vec<Route>, ScriptRepositoryError> {
+        let rows = sqlx::query_as::<_, RouteRow>(
+            "SELECT id, script_id, host_kind, host, host_param_name, \
+                    path_kind, path, method, created_at \
+             FROM routes WHERE script_id = $1 ORDER BY created_at",
+        )
+        .bind(script_id.into_inner())
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    async fn create(&self, input: NewRoute) -> Result<Route, ScriptRepositoryError> {
+        let res = sqlx::query_as::<_, RouteRow>(
+            "INSERT INTO routes ( \
+                script_id, host_kind, host, host_param_name, \
+                path_kind, path, method \
+             ) VALUES ($1, $2, $3, $4, $5, $6, $7) \
+             RETURNING id, script_id, host_kind, host, host_param_name, \
+                       path_kind, path, method, created_at",
+        )
+        .bind(input.script_id.into_inner())
+        .bind(host_kind_str(input.host_kind))
+        .bind(&input.host)
+        .bind(input.host_param_name.as_deref())
+        .bind(path_kind_str(input.path_kind))
+        .bind(&input.path)
+        .bind(input.method.as_deref())
+        .fetch_one(&self.pool)
+        .await;
+
+        match res {
+            Ok(row) => Ok(row.into()),
+            Err(sqlx::Error::Database(e)) if e.is_unique_violation() => Err(
+                ScriptRepositoryError::Conflict("a route with this binding already exists".into()),
+            ),
+            Err(sqlx::Error::Database(e)) if e.is_foreign_key_violation() => {
+                Err(ScriptRepositoryError::NotFound(input.script_id))
+            }
+            Err(e) => Err(e.into()),
+        }
+    }
+
+    async fn delete(&self, route_id: Uuid) -> Result<(), ScriptRepositoryError> {
+        let res = sqlx::query("DELETE FROM routes WHERE id = $1")
+            .bind(route_id)
+            .execute(&self.pool)
+            .await?;
+        if res.rows_affected() == 0 {
+            return Err(ScriptRepositoryError::NotFound(ScriptId::from(route_id)));
+        }
+        Ok(())
+    }
+}
+
+const fn host_kind_str(k: HostKind) -> &'static str {
+    match k {
+        HostKind::Any => "any",
+        HostKind::Strict => "strict",
+        HostKind::Wildcard => "wildcard",
+    }
+}
+
+const fn path_kind_str(k: PathKind) -> &'static str {
+    match k {
+        PathKind::Exact => "exact",
+        PathKind::Prefix => "prefix",
+        PathKind::Param => "param",
+    }
+}
+
+#[derive(sqlx::FromRow)]
+struct RouteRow {
+    id: Uuid,
+    script_id: Uuid,
+    host_kind: String,
+    host: String,
+    host_param_name: Option<String>,
+    path_kind: String,
+    path: String,
+    method: Option<String>,
+    created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl From<RouteRow> for Route {
+    fn from(r: RouteRow) -> Self {
+        Self {
+            id: r.id,
+            script_id: r.script_id.into(),
+            host_kind: match r.host_kind.as_str() {
+                "strict" => HostKind::Strict,
+                "wildcard" => HostKind::Wildcard,
+                _ => HostKind::Any,
+            },
+            host: r.host,
+            host_param_name: r.host_param_name,
+            path_kind: match r.path_kind.as_str() {
+                "prefix" => PathKind::Prefix,
+                "param" => PathKind::Param,
+                _ => PathKind::Exact,
+            },
+            path: r.path,
+            method: r.method,
+            created_at: r.created_at,
+        }
+    }
+}