feat(v1.1.2-docs): manager-core docs service + repo + query DSL parser

DocsServiceImpl mirrors KvServiceImpl's script-as-gate authz pattern,
the empty-collection rejection, and the best-effort emitter call —
adding "data must be a JSON object" validation, NotFound on update of
a missing doc, and prev_data plumbing via repo.update returning the
prior data.

PostgresDocsRepo handles CRUD against the docs table. The find path
runs through the v1.1.2 query DSL parser (docs_filter::parse_filter)
before building parameterised SQL via sqlx::QueryBuilder:

  * Every field-path segment + comparison value is bound as $N.
  * jsonb_extract_path_text(data, $N1, $N2, ...) handles variable
    depth without segment interpolation.
  * Base WHERE is fixed: WHERE app_id = $1 AND collection = $2.
    Filter conditions can only narrow, never widen. Load-bearing
    test in sql_shape_tests pins this prefix on every emitted query
    + asserts no user string ever lands in the SQL text.
  * $ne uses IS DISTINCT FROM (not <>) so missing paths + JSON nulls
    are correctly included.
  * $in binds the value list as TEXT[] via = ANY($N::text[]).
  * $sort always appends a ", id ASC" tiebreaker for stable cursor
    pagination semantics; $limit is clamped to MAX_FIND_LIMIT.

docs_filter is the AST + parser for the DSL. Operator allowlist is
explicit; any non-v1.1.2 operator throws UnsupportedOperator with a
v1.2 pointer. Snapshot tests pin the SDK-contract error strings so
changing them is a deliberate act.

Two new Capability variants — AppDocsRead and AppDocsWrite — map to
the existing Scope::ScriptRead and ScriptWrite per the seven-scope
commitment from v1.1.0. role_satisfies grants read at Viewer,
write at Editor (same trust shape as KV).

59 unit tests added across the three new files. All pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-02 19:55:14 +02:00
parent 3af8cc38c9
commit 06678f4496
5 changed files with 2071 additions and 6 deletions

View File

@@ -64,6 +64,14 @@ pub enum Capability {
/// Write entries to this app's KV store (v1.1.1). Granted to
/// `editor`+. Maps to `script:write` on API keys.
AppKvWrite(AppId),
/// Read documents from this app's docs store (v1.1.2). Same trust
/// shape as KV read — granted to `viewer`+, maps to `script:read`
/// on API keys. Honors the seven-scope commitment.
AppDocsRead(AppId),
/// Write documents to this app's docs store (v1.1.2). Same trust
/// shape as KV write — granted to `editor`+, maps to
/// `script:write` on API keys.
AppDocsWrite(AppId),
/// Create / list / delete triggers for this app (v1.1.1). Maps to
/// `app:admin` on API keys — triggers are app-configuration acts
/// rather than data-plane access. Granted to `app_admin`+.
@@ -91,6 +99,8 @@ impl Capability {
| Self::AppLogRead(id)
| Self::AppKvRead(id)
| Self::AppKvWrite(id)
| Self::AppDocsRead(id)
| Self::AppDocsWrite(id)
| Self::AppManageTriggers(id)
| Self::AppDeadLetterManage(id) => Some(id),
}
@@ -107,8 +117,10 @@ impl Capability {
Self::InstanceCreateApp | Self::InstanceManageUsers | Self::InstanceManageSettings => {
Scope::InstanceAdmin
}
Self::AppRead(_) | Self::AppKvRead(_) => Scope::ScriptRead,
Self::AppWriteScript(_) | Self::AppKvWrite(_) => Scope::ScriptWrite,
Self::AppRead(_) | Self::AppKvRead(_) | Self::AppDocsRead(_) => Scope::ScriptRead,
Self::AppWriteScript(_) | Self::AppKvWrite(_) | Self::AppDocsWrite(_) => {
Scope::ScriptWrite
}
Self::AppWriteRoute(_) => Scope::RouteWrite,
Self::AppManageDomains(_) => Scope::DomainManage,
Self::AppAdmin(_) | Self::AppManageTriggers(_) | Self::AppDeadLetterManage(_) => {
@@ -253,7 +265,10 @@ async fn member_grants(
const fn role_satisfies(role: AppRole, cap: Capability) -> bool {
let in_viewer = matches!(
cap,
Capability::AppRead(_) | Capability::AppLogRead(_) | Capability::AppKvRead(_)
Capability::AppRead(_)
| Capability::AppLogRead(_)
| Capability::AppKvRead(_)
| Capability::AppDocsRead(_)
);
let in_editor = in_viewer
|| matches!(
@@ -261,6 +276,7 @@ const fn role_satisfies(role: AppRole, cap: Capability) -> bool {
Capability::AppWriteScript(_)
| Capability::AppWriteRoute(_)
| Capability::AppKvWrite(_)
| Capability::AppDocsWrite(_)
);
let in_app_admin = in_editor
|| matches!(