fabi/PiCloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: custom routing — bind scripts to your own URLs

Browse Source 
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>
This commit is contained in:
MechaCat02
2026-05-23 18:18:16 +02:00
parent f51924fdbc
commit 07e2a62d98
36 changed files with 2449 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
crates/picloud/tests/api.rs
View File

@@ -17,8 +17,9 @@ use axum_test::TestServer;
use serde_json::{json, Value};
use sqlx::PgPool;
fn server(pool: PgPool) -> TestServer {
TestServer::new(picloud::build_app(pool)).expect("TestServer should build")
async fn server(pool: PgPool) -> TestServer {
let app = picloud::build_app(pool).await.expect("build_app");
TestServer::new(app).expect("TestServer should build")
}
// ============================================================================
@@ -28,7 +29,7 @@ fn server(pool: PgPool) -> TestServer {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn healthz_responds_ok(pool: PgPool) {
let r = server(pool).get("/healthz").await;
let r = server(pool).await.get("/healthz").await;
r.assert_status_ok();
assert_eq!(r.text(), "ok");
}
@@ -40,7 +41,7 @@ async fn healthz_responds_ok(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn create_script_returns_201_with_full_record(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let r = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -61,6 +62,7 @@ async fn create_script_returns_201_with_full_record(pool: PgPool) {
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn create_with_invalid_syntax_returns_422(pool: PgPool) {
let r = server(pool)
.await
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "broken", "source": "@@@ not rhai @@@" }))
.await;
@@ -72,7 +74,7 @@ async fn create_with_invalid_syntax_returns_422(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn duplicate_name_returns_409(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
s.post("/api/v1/admin/scripts")
.json(&json!({ "name": "dup", "source": "42" }))
.await
@@ -87,7 +89,7 @@ async fn duplicate_name_returns_409(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn list_returns_all_scripts(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
for name in ["alpha", "bravo", "charlie"] {
s.post("/api/v1/admin/scripts")
.json(&json!({ "name": name, "source": "1" }))
@@ -105,7 +107,7 @@ async fn list_returns_all_scripts(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn update_bumps_version_and_persists_changes(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "u", "source": "1" }))
@@ -127,7 +129,7 @@ async fn update_bumps_version_and_persists_changes(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn update_with_invalid_source_returns_422(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "u", "source": "1" }))
@@ -145,7 +147,7 @@ async fn update_with_invalid_source_returns_422(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn delete_then_get_returns_404(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "d", "source": "1" }))
@@ -166,6 +168,7 @@ async fn delete_then_get_returns_404(pool: PgPool) {
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn get_nonexistent_returns_404(pool: PgPool) {
let r = server(pool)
.await
.get("/api/v1/admin/scripts/00000000-0000-0000-0000-000000000000")
.await;
r.assert_status_not_found();
@@ -178,7 +181,7 @@ async fn get_nonexistent_returns_404(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn execute_echoes_body_back(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -201,7 +204,7 @@ async fn execute_echoes_body_back(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn execute_passes_through_status_and_headers(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -224,6 +227,7 @@ async fn execute_passes_through_status_and_headers(pool: PgPool) {
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn execute_nonexistent_returns_404(pool: PgPool) {
let r = server(pool)
.await
.post("/api/v1/execute/00000000-0000-0000-0000-000000000000")
.json(&json!({}))
.await;
@@ -233,7 +237,7 @@ async fn execute_nonexistent_returns_404(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn execution_logs_capture_invocations(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -290,7 +294,7 @@ async fn execution_logs_capture_invocations(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn create_without_sandbox_returns_empty_object(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "no-sandbox", "source": "1" }))
@@ -302,7 +306,7 @@ async fn create_without_sandbox_returns_empty_object(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn create_with_sandbox_persists_and_returns_overrides(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -329,7 +333,7 @@ async fn create_with_sandbox_persists_and_returns_overrides(pool: PgPool) {
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn sandbox_exceeding_ceiling_returns_422(pool: PgPool) {
// Default conservative ceiling caps max_operations at 10_000_000.
let s = server(pool);
let s = server(pool).await;
let r = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -346,7 +350,7 @@ async fn sandbox_exceeding_ceiling_returns_422(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn sandbox_unknown_field_returns_422(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let r = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -367,7 +371,7 @@ async fn sandbox_unknown_field_returns_422(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn sandbox_overrides_take_effect_at_execute(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
// Tight max_operations on a loop the default would happily run.
let created: Value = s
.post("/api/v1/admin/scripts")
@@ -392,7 +396,7 @@ async fn sandbox_overrides_take_effect_at_execute(pool: PgPool) {
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn update_replaces_sandbox_wholesale(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({
@@ -421,10 +425,296 @@ async fn update_replaces_sandbox_wholesale(pool: PgPool) {
assert_eq!(cleared["sandbox"], json!({}));
}
// ============================================================================
// Custom routing
// ============================================================================
async fn create_basic_script(s: &TestServer, name: &str, source: &str) -> String {
let v: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({ "name": name, "source": source }))
.await
.json();
v["id"].as_str().unwrap().to_string()
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_exact_dispatches_to_script(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(
&s,
"greet",
"#{ statusCode: 200, body: #{ msg: \"hi\", path: ctx.request.path } }",
)
.await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "exact",
"path": "/greet"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s.get("/greet").await;
r.assert_status_ok();
let body: Value = r.json();
assert_eq!(body["msg"], "hi");
assert_eq!(body["path"], "/greet");
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_param_captures_path_vars(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(
&s,
"greet-name",
"#{ statusCode: 200, body: #{ name: ctx.request.params.name } }",
)
.await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/greet/:name"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s.get("/greet/alice").await;
r.assert_status_ok();
let body: Value = r.json();
assert_eq!(body["name"], "alice");
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_prefix_captures_rest(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(
&s,
"echo-prefix",
"#{ statusCode: 200, body: #{ rest: ctx.request.rest } }",
)
.await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "prefix",
"path": "/echo/*"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s.get("/echo/foo/bar").await;
r.assert_status_ok();
let body: Value = r.json();
assert_eq!(body["rest"], "foo/bar");
s.get("/echo").await.assert_status_not_found();
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_query_string_exposed_to_script(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "qs", "#{ statusCode: 200, body: ctx.request.query }").await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "exact",
"path": "/qs"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s.get("/qs?a=1&b=two").await;
r.assert_status_ok();
let body: Value = r.json();
assert_eq!(body, json!({ "a": "1", "b": "two" }));
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_invalid_pattern_returns_422(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "x", "1").await;
let r = s
.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/greet/my:name"
}))
.await;
r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_conflict_returns_409(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "x", "1").await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/users/:id"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s
.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/users/:userId"
}))
.await;
r.assert_status(axum::http::StatusCode::CONFLICT);
let body: Value = r.json();
assert!(body["conflicting_route"].is_object());
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_reserved_path_returns_422(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "x", "1").await;
let r = s
.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "exact",
"path": "/admin/foo"
}))
.await;
r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_match_preview_endpoint(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "g", "1").await;
s.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/greet/:name"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s
.post("/api/v1/admin/routes:match")
.json(&json!({ "url": "http://localhost:8000/greet/alice", "method": "GET" }))
.await;
r.assert_status_ok();
let body: Value = r.json();
assert!(body["matched"].is_object());
assert_eq!(body["matched"]["params"]["name"], "alice");
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_delete_removes_dispatch(pool: PgPool) {
let s = server(pool).await;
let id = create_basic_script(&s, "g", "#{ statusCode: 200, body: 1 }").await;
let created: Value = s
.post(&format!("/api/v1/admin/scripts/{id}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "exact",
"path": "/g"
}))
.await
.json();
let route_id = created["id"].as_str().unwrap();
s.get("/g").await.assert_status_ok();
s.delete(&format!("/api/v1/admin/routes/{route_id}"))
.await
.assert_status(axum::http::StatusCode::NO_CONTENT);
s.get("/g").await.assert_status_not_found();
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn route_specificity_param_beats_prefix(pool: PgPool) {
let s = server(pool).await;
let id_p = create_basic_script(
&s,
"by-param",
"#{ statusCode: 200, body: #{ tag: \"param\" } }",
)
.await;
let id_pr = create_basic_script(
&s,
"by-prefix",
"#{ statusCode: 200, body: #{ tag: \"prefix\" } }",
)
.await;
s.post(&format!("/api/v1/admin/scripts/{id_p}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "param",
"path": "/foo/:bar"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
s.post(&format!("/api/v1/admin/scripts/{id_pr}/routes"))
.json(&json!({
"host_kind": "any",
"path_kind": "prefix",
"path": "/foo/*"
}))
.await
.assert_status(axum::http::StatusCode::CREATED);
// Single segment under /foo/ — both match; param wins by spec.
let r = s.get("/foo/x").await;
let body: Value = r.json();
assert_eq!(body["tag"], "param");
// Two segments — only prefix matches.
let r2 = s.get("/foo/x/y").await;
let body2: Value = r2.json();
assert_eq!(body2["tag"], "prefix");
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn root_returns_404_when_no_route(pool: PgPool) {
let s = server(pool).await;
let r = s.get("/").await;
r.assert_status_not_found();
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn version_includes_public_base_url(pool: PgPool) {
let s = server(pool).await;
let r = s.get("/version").await;
r.assert_status_ok();
let v: Value = r.json();
assert!(v["public_base_url"].is_string());
assert_eq!(v["api"], 1);
assert_eq!(v["schema"], 3);
assert_eq!(v["sdk"], "1.1");
}
// ============================================================================
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn execution_errors_are_still_logged(pool: PgPool) {
let s = server(pool);
let s = server(pool).await;
let created: Value = s
.post("/api/v1/admin/scripts")
.json(&json!({