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

feat: versioning scheme — lockstep crates + four independent surfaces

Browse Source 
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>
This commit is contained in:
MechaCat02
2026-05-23 00:31:08 +02:00
parent 777f4af628
commit 0473d295af
23 changed files with 356 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
crates/executor-core/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-executor-core"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

3
crates/executor-core/src/engine.rs
View File

@@ -3,7 +3,7 @@ use std::sync::{Arc, Mutex};
use std::time::Instant;
use chrono::Utc;
use picloud_shared::{ScriptValidator, ValidationError};
use picloud_shared::{ScriptValidator, ValidationError, SDK_VERSION};
use rhai::{Dynamic, Engine as RhaiEngine, EvalAltResult, Map, Module, Scope};
use serde_json::Value as Json;
@@ -172,6 +172,7 @@ fn push_log(logs: &Arc<Mutex<Vec<LogEntry>>>, level: LogLevel, message: &str, da
fn build_ctx_map(req: &ExecRequest) -> Map {
let mut ctx = Map::new();
ctx.insert("sdk_version".into(), SDK_VERSION.into());
ctx.insert("execution_id".into(), req.execution_id.to_string().into());
ctx.insert("script_id".into(), req.script_id.to_string().into());
ctx.insert("script_name".into(), req.script_name.clone().into());

14
crates/executor-core/tests/engine.rs
View File

@@ -143,6 +143,20 @@ fn module_import_is_blocked() {
assert!(matches!(err, ExecError::Runtime(_) | ExecError::Parse(_)));
}
#[test]
fn ctx_exposes_sdk_version() {
let resp = engine()
.execute("ctx.sdk_version", req(json!(null)))
.unwrap();
// Whatever it is, it must look like "MAJOR.MINOR" — that's the
// contract scripts feature-detect against.
let v = resp.body.as_str().expect("sdk_version is a string");
let parts: Vec<&str> = v.split('.').collect();
assert_eq!(parts.len(), 2, "expected major.minor, got {v:?}");
assert!(parts[0].parse::<u32>().is_ok(), "major not numeric: {v:?}");
assert!(parts[1].parse::<u32>().is_ok(), "minor not numeric: {v:?}");
}
#[test]
fn body_passes_through_nested_json_round_trip() {
let src = "#{ statusCode: 200, body: ctx.request.body }";

2
crates/manager-core/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-manager-core"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

12
crates/manager-core/src/migrations.rs
View File

@@ -7,3 +7,15 @@ use sqlx::PgPool;
pub async fn run(pool: &PgPool) -> Result<(), sqlx::migrate::MigrateError> {
sqlx::migrate!("./migrations").run(pool).await
}
/// Highest embedded migration version. This is the schema version the
/// binary expects to find applied — surfaced from `/version` so peers
/// and operators can verify schema compatibility at a glance.
#[must_use]
pub fn latest_version() -> i64 {
sqlx::migrate!("./migrations")
.iter()
.map(|m| m.version)
.max()
.unwrap_or(0)
}

2
crates/orchestrator-core/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-orchestrator-core"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

2
crates/picloud-executor/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-executor"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

2
crates/picloud-manager/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-manager"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

2
crates/picloud-orchestrator/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-orchestrator"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

2
crates/picloud/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

36
crates/picloud/src/lib.rs
View File

@@ -6,20 +6,27 @@
use std::sync::Arc;
use std::time::Duration;
use axum::{routing::get, Router};
use axum::{routing::get, Json, Router};
use picloud_executor_core::{Engine, Limits};
use picloud_manager_core::{
admin_router, AdminState, PostgresExecutionLogRepository, PostgresExecutionLogSink,
admin_router, migrations, AdminState, PostgresExecutionLogRepository, PostgresExecutionLogSink,
PostgresScriptRepository, RepoResolver,
};
use picloud_orchestrator_core::{data_plane_router, DataPlaneState, LocalExecutorClient};
use picloud_shared::{ExecutionLogSink, ScriptValidator};
use picloud_shared::{
ExecutionLogSink, ScriptValidator, API_VERSION, PRODUCT_VERSION, SDK_VERSION, WIRE_VERSION,
};
use sqlx::postgres::PgPoolOptions;
use sqlx::PgPool;
use tower_http::trace::TraceLayer;
/// Compose the manager + orchestrator routes on top of a shared
/// Postgres pool, returning an Axum router ready to be served.
///
/// All API routes live under `/api/v{API_VERSION}/...`. New major
/// versions get a parallel nest under `/api/v{N+1}/...`; the old
/// prefix is kept live for at least one product-minor deprecation
/// window (see `docs/versioning.md`).
pub fn build_app(pool: PgPool) -> Router {
let engine = Arc::new(Engine::new(Limits::default()));
@@ -43,11 +50,15 @@ pub fn build_app(pool: PgPool) -> Router {
log_sink,
};
let api_v1 = Router::new()
.nest("/admin", admin_router(admin))
.merge(data_plane_router(data_plane));
Router::new()
.route("/healthz", get(healthz))
.route("/version", get(version))
.route("/", get(root))
.nest("/api/admin", admin_router(admin))
.nest("/api", data_plane_router(data_plane))
.nest(&format!("/api/v{API_VERSION}"), api_v1)
.layer(TraceLayer::new_for_http())
}
@@ -67,7 +78,20 @@ async fn healthz() -> &'static str {
}
async fn root() -> &'static str {
"picloud — see /api/admin/* (manager) and /api/execute/* (orchestrator)"
"picloud — see /api/v1/admin/* (manager), /api/v1/execute/* (orchestrator), /version"
}
/// Snapshot of every compatibility-surface version this process speaks.
/// Documented in `docs/versioning.md`; the source of truth is
/// `shared::version` plus the embedded migrations.
async fn version() -> Json<serde_json::Value> {
Json(serde_json::json!({
"product": PRODUCT_VERSION,
"sdk": SDK_VERSION,
"api": API_VERSION,
"schema": migrations::latest_version(),
"wire": WIRE_VERSION,
}))
}
// ----------------------------------------------------------------------------

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

@@ -42,7 +42,7 @@ async fn healthz_responds_ok(pool: PgPool) {
async fn create_script_returns_201_with_full_record(pool: PgPool) {
let s = server(pool);
let r = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({
"name": "echo",
"description": "test",
@@ -61,7 +61,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)
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "broken", "source": "@@@ not rhai @@@" }))
.await;
r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
@@ -73,12 +73,12 @@ async fn create_with_invalid_syntax_returns_422(pool: PgPool) {
#[sqlx::test(migrations = "../manager-core/migrations")]
async fn duplicate_name_returns_409(pool: PgPool) {
let s = server(pool);
s.post("/api/admin/scripts")
s.post("/api/v1/admin/scripts")
.json(&json!({ "name": "dup", "source": "42" }))
.await
.assert_status(axum::http::StatusCode::CREATED);
let r = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "dup", "source": "43" }))
.await;
r.assert_status(axum::http::StatusCode::CONFLICT);
@@ -89,12 +89,12 @@ async fn duplicate_name_returns_409(pool: PgPool) {
async fn list_returns_all_scripts(pool: PgPool) {
let s = server(pool);
for name in ["alpha", "bravo", "charlie"] {
s.post("/api/admin/scripts")
s.post("/api/v1/admin/scripts")
.json(&json!({ "name": name, "source": "1" }))
.await
.assert_status(axum::http::StatusCode::CREATED);
}
let r = s.get("/api/admin/scripts").await;
let r = s.get("/api/v1/admin/scripts").await;
r.assert_status_ok();
let body: Vec<Value> = r.json();
assert_eq!(body.len(), 3);
@@ -107,14 +107,14 @@ async fn list_returns_all_scripts(pool: PgPool) {
async fn update_bumps_version_and_persists_changes(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "u", "source": "1" }))
.await
.json();
let id = created["id"].as_str().unwrap();
let r = s
.put(&format!("/api/admin/scripts/{id}"))
.put(&format!("/api/v1/admin/scripts/{id}"))
.json(&json!({ "source": "#{ statusCode: 200, body: \"v2\" }", "timeout_seconds": 60 }))
.await;
r.assert_status_ok();
@@ -129,14 +129,14 @@ async fn update_bumps_version_and_persists_changes(pool: PgPool) {
async fn update_with_invalid_source_returns_422(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "u", "source": "1" }))
.await
.json();
let id = created["id"].as_str().unwrap();
let r = s
.put(&format!("/api/admin/scripts/{id}"))
.put(&format!("/api/v1/admin/scripts/{id}"))
.json(&json!({ "source": "@@@ broken @@@" }))
.await;
r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
@@ -147,17 +147,17 @@ async fn update_with_invalid_source_returns_422(pool: PgPool) {
async fn delete_then_get_returns_404(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({ "name": "d", "source": "1" }))
.await
.json();
let id = created["id"].as_str().unwrap();
s.delete(&format!("/api/admin/scripts/{id}"))
s.delete(&format!("/api/v1/admin/scripts/{id}"))
.await
.assert_status(axum::http::StatusCode::NO_CONTENT);
s.get(&format!("/api/admin/scripts/{id}"))
s.get(&format!("/api/v1/admin/scripts/{id}"))
.await
.assert_status_not_found();
}
@@ -166,7 +166,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)
.get("/api/admin/scripts/00000000-0000-0000-0000-000000000000")
.get("/api/v1/admin/scripts/00000000-0000-0000-0000-000000000000")
.await;
r.assert_status_not_found();
}
@@ -180,7 +180,7 @@ async fn get_nonexistent_returns_404(pool: PgPool) {
async fn execute_echoes_body_back(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({
"name": "echo",
"source": "#{ statusCode: 200, body: ctx.request.body }",
@@ -190,7 +190,7 @@ async fn execute_echoes_body_back(pool: PgPool) {
let id = created["id"].as_str().unwrap();
let r = s
.post(&format!("/api/execute/{id}"))
.post(&format!("/api/v1/execute/{id}"))
.json(&json!({ "n": 42 }))
.await;
r.assert_status_ok();
@@ -203,7 +203,7 @@ async fn execute_echoes_body_back(pool: PgPool) {
async fn execute_passes_through_status_and_headers(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({
"name": "header-test",
"source": "#{ statusCode: 201, headers: #{ \"x-tag\": \"on\" }, body: 1 }",
@@ -212,7 +212,10 @@ async fn execute_passes_through_status_and_headers(pool: PgPool) {
.json();
let id = created["id"].as_str().unwrap();
let r = s.post(&format!("/api/execute/{id}")).json(&json!({})).await;
let r = s
.post(&format!("/api/v1/execute/{id}"))
.json(&json!({}))
.await;
r.assert_status(axum::http::StatusCode::CREATED);
assert_eq!(r.header("x-tag"), "on");
}
@@ -221,7 +224,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)
.post("/api/execute/00000000-0000-0000-0000-000000000000")
.post("/api/v1/execute/00000000-0000-0000-0000-000000000000")
.json(&json!({}))
.await;
r.assert_status_not_found();
@@ -232,7 +235,7 @@ async fn execute_nonexistent_returns_404(pool: PgPool) {
async fn execution_logs_capture_invocations(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({
"name": "logger",
"source": "log::info(\"called\", #{ marker: 7 }); #{ statusCode: 200, body: \"done\" }",
@@ -242,22 +245,25 @@ async fn execution_logs_capture_invocations(pool: PgPool) {
let id = created["id"].as_str().unwrap();
// No logs yet.
let r = s.get(&format!("/api/admin/scripts/{id}/logs")).await;
let r = s.get(&format!("/api/v1/admin/scripts/{id}/logs")).await;
r.assert_status_ok();
let logs: Vec<Value> = r.json();
assert!(logs.is_empty());
// Two invocations.
s.post(&format!("/api/execute/{id}"))
s.post(&format!("/api/v1/execute/{id}"))
.json(&json!({ "first": true }))
.await
.assert_status_ok();
s.post(&format!("/api/execute/{id}"))
s.post(&format!("/api/v1/execute/{id}"))
.json(&json!({ "second": true }))
.await
.assert_status_ok();
let logs: Vec<Value> = s.get(&format!("/api/admin/scripts/{id}/logs")).await.json();
let logs: Vec<Value> = s
.get(&format!("/api/v1/admin/scripts/{id}/logs"))
.await
.json();
assert_eq!(logs.len(), 2);
// Most-recent-first ordering.
@@ -282,7 +288,7 @@ async fn execution_logs_capture_invocations(pool: PgPool) {
async fn execution_errors_are_still_logged(pool: PgPool) {
let s = server(pool);
let created: Value = s
.post("/api/admin/scripts")
.post("/api/v1/admin/scripts")
.json(&json!({
"name": "boom",
"source": "1 / 0",
@@ -291,10 +297,16 @@ async fn execution_errors_are_still_logged(pool: PgPool) {
.json();
let id = created["id"].as_str().unwrap();
let r = s.post(&format!("/api/execute/{id}")).json(&json!({})).await;
let r = s
.post(&format!("/api/v1/execute/{id}"))
.json(&json!({}))
.await;
r.assert_status(axum::http::StatusCode::BAD_GATEWAY);
let logs: Vec<Value> = s.get(&format!("/api/admin/scripts/{id}/logs")).await.json();
let logs: Vec<Value> = s
.get(&format!("/api/v1/admin/scripts/{id}/logs"))
.await
.json();
assert_eq!(logs.len(), 1);
assert_eq!(logs[0]["status"], "error");
assert!(logs[0]["response_body"]["error"].is_string());

2
crates/shared/Cargo.toml
View File

@@ -1,6 +1,6 @@
[package]
name = "picloud-shared"
version = "0.1.0"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

2
crates/shared/src/lib.rs
View File

@@ -10,6 +10,7 @@ pub mod ids;
pub mod log_sink;
pub mod script;
pub mod validator;
pub mod version;
pub use error::Error;
pub use execution_log::{ExecutionLog, ExecutionStatus};
@@ -17,3 +18,4 @@ pub use ids::{ExecutionId, RequestId, ScriptId};
pub use log_sink::{ExecutionLogSink, LogSinkError};
pub use script::Script;
pub use validator::{ScriptValidator, ValidationError};
pub use version::{API_VERSION, PRODUCT_VERSION, SDK_VERSION, WIRE_VERSION};

31
crates/shared/src/version.rs Normal file
View File

@@ -0,0 +1,31 @@
//! Version constants for PiCloud's compatibility surfaces.
//!
//! See [`docs/versioning.md`](../../../../docs/versioning.md) for the
//! full scheme. The product version is sourced from the workspace
//! package version; the four surface versions live in this module
//! and are bumped under the rules in that doc.
/// Product version (e.g. `"0.2.0"`). Sourced from this crate's
/// `Cargo.toml` so the workspace-inherited package version is the
/// single point of update.
pub const PRODUCT_VERSION: &str = env!("CARGO_PKG_VERSION");
/// Rhai SDK version, in `"major.minor"` form. Scripts read this from
/// `ctx.sdk_version` for feature detection. Bump rules:
/// * patch (`1.0.x`): doc-only, no script-observable change
/// * minor (`1.0 → 1.1`): added functions / fields; existing
/// scripts must still run unchanged
/// * major (`1 → 2`): removed, renamed, retyped, restricted
pub const SDK_VERSION: &str = "1.0";
/// HTTP API major version. Appears in URL paths as `/api/v{N}/...`.
/// Bump (new integer + new URL prefix) when the request/response
/// shape, status-code semantics, or auth model changes. The previous
/// major is kept live for at least one product-minor deprecation
/// window.
pub const API_VERSION: u32 = 1;
/// Wire-protocol version between manager / orchestrator / executor
/// nodes in cluster mode. Negotiated via the `X-PiCloud-Wire` header
/// on inter-service requests. Reserved at `1`; cluster mode is v1.3+.
pub const WIRE_VERSION: u32 = 1;