feat(v1.1.3-modules): shared types, migrations, engine + resolver scaffold

Lays down the v1.1.3 plumbing:

- `ScriptKind` enum in `picloud-shared` ('endpoint' | 'module').
- `ModuleSource` trait + `ModuleScript` DTO + `NoopModuleSource` in
  `picloud-shared`. Resolver lives in `executor-core`; Postgres impl
  in `manager-core` (`PostgresModuleSource`).
- `Services::new` grows a fifth `modules: Arc<dyn ModuleSource>` arg.
- `ScriptValidator` returns `ValidatedScript { imports }` so the
  manager can populate the dep-graph table on save. New
  `validate_module` method on the trait gates module-shape rules.
- `Engine::execute_ast(&Arc<rhai::AST>, req)` lets the orchestrator's
  script cache reuse compiled ASTs. `Engine::execute(&str, req)` is
  preserved as a convenience that compiles inline. `Engine::compile`
  exposes the AST for callers that want to cache.
- `PicloudModuleResolver` replaces `DummyModuleResolver` per-call.
  Bridges Rhai's sync `ModuleResolver::resolve` to async
  `ModuleSource::lookup` via `Handle::block_on`. Enforces:
  - cross-app isolation (resolver captures `Arc<SdkCallCx>`),
  - circular import detection (in-progress stack on the resolver),
  - import depth limit (default 8 via
    `Limits::module_import_depth_max`).
- Module-shape validation walks `ast.statements()` via `rhai/internals`
  and accepts only `Var { CONSTANT }`, `Import`, and `Noop`. The
  manager admin endpoint runs `validate_module` at save (primary
  gate); resolver re-runs it at load (defense in depth).
- LRU cache `(AppId, name) -> (updated_at, Arc<Module>)` owned by
  `Engine`. Size from `PICLOUD_MODULE_CACHE_SIZE` (default 512).
- Migration `0015_scripts_kind.sql` adds `scripts.kind` + composite
  index + module-name shape CHECK.
- Migration `0016_script_imports.sql` adds the dep-graph table with
  FK CASCADE on both columns.
- Repo: `kind` threaded through SELECT/INSERT/UPDATE. New
  `count_routes_for_script` / `count_triggers_for_script` /
  `list_imports` methods. `create`/`update` open a transaction and
  call `replace_imports_tx` to populate the dep-graph.
- Admin endpoint: accepts `kind`; rejects reserved module names;
  rejects `endpoint → module` transitions when routes / triggers
  exist.
- SDK_VERSION 1.3 → 1.4.

Workspace builds; full test suite (~440 tests) green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-02 22:04:21 +02:00
parent 5bbbc26c84
commit 84833d3e4e
23 changed files with 1231 additions and 85 deletions

View File

@@ -0,0 +1,31 @@
-- v1.1.3: distinguish endpoint scripts (HTTP / trigger entry points) from
-- module scripts (libraries `import`ed by other scripts). The Rhai module
-- resolver added in v1.1.3 looks up `kind = 'module'` rows by
-- `(app_id, name)`; route bind and trigger create reject `kind = 'module'`
-- targets.
--
-- Backfill: existing rows take the DEFAULT clause on column add. Every
-- script that existed in v1.0 / v1.1.0 / v1.1.1 / v1.1.2 was an endpoint
-- (the only kind those versions supported), which matches the default.
ALTER TABLE scripts
ADD COLUMN kind TEXT NOT NULL DEFAULT 'endpoint'
CHECK (kind IN ('endpoint', 'module'));
-- Composite index on (app_id, kind) so the resolver's per-app module
-- lookup ("modules in app X named Y") is one index scan. The existing
-- per-app UNIQUE on `name` already serves name-based lookups, but it
-- doesn't help when filtering specifically for `kind = 'module'`.
CREATE INDEX idx_scripts_app_kind ON scripts (app_id, kind);
-- Modules are imported by exact string name; arbitrary spaces / control
-- characters would make `import "<name>"` fragile. We constrain module
-- names to a conservative identifier shape (letters, digits, underscore;
-- starts with a non-digit; up to 64 chars). Endpoint scripts keep the
-- looser pre-v1.1.3 name rules — the dashboard generates endpoint names
-- (and some users may already have spaces in them; we don't break those).
ALTER TABLE scripts
ADD CONSTRAINT scripts_module_name_shape
CHECK (
kind <> 'module'
OR name ~ '^[a-zA-Z_][a-zA-Z0-9_]{0,63}$'
);

View File

@@ -0,0 +1,35 @@
-- v1.1.3: dep graph between scripts and the modules they `import`.
--
-- Populated at script save-time. The validator extracts literal-path
-- `import "<name>"` declarations from the AST; the script repo writes
-- one row per resolved (importer, imported) pair inside the same
-- transaction as the INSERT/UPDATE on `scripts`. Unresolved names
-- (imported module doesn't exist yet) are silently skipped — the
-- resolver returns ErrorModuleNotFound at runtime, and a later save
-- of either script re-resolves and writes the edge.
--
-- Dynamic imports (`import some_var as alias;`) are not tracked
-- here — the resolver still honors them at runtime, but the graph
-- only captures names known at compile time. Document as a known
-- v1.1.3 limitation.
--
-- Purpose: drives a future "Used by" panel on a module's detail page
-- (v1.2+) and is the foundation for cluster-mode eager cache
-- invalidation (v1.3+). v1.1.3 only persists the rows; no admin
-- endpoint surfaces them yet.
CREATE TABLE script_imports (
app_id UUID NOT NULL REFERENCES apps(id) ON DELETE CASCADE,
importer_script_id UUID NOT NULL REFERENCES scripts(id) ON DELETE CASCADE,
imported_script_id UUID NOT NULL REFERENCES scripts(id) ON DELETE CASCADE,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (importer_script_id, imported_script_id)
);
-- Reverse-edge index: "list scripts that import module X". The PK
-- covers (importer, imported) so forward lookups by importer are
-- already free; the reverse direction needs its own index.
CREATE INDEX idx_script_imports_imported ON script_imports (imported_script_id);
-- App-scoped scan ("all imports in this app") — used by the schema
-- snapshot tests and (eventually) the admin "audit" view.
CREATE INDEX idx_script_imports_app ON script_imports (app_id);