@loradb/lora-graphql 0.16.2 → 0.18.0

package/README.md

@@ -109,16 +109,17 @@ Model:
 | `@key(generate:)`                                                                                          | field             | Required, unique and immutable. The sort tie-breaker, cursor anchor and mutation address. `generate: true` fills a UUID on create                                                                                                        |
 | `@unique`                                                                                                  | field             | Uniqueness constraint                                                                                                                                                                                                                    |
 | `@index(kind: RANGE \| TEXT \| POINT)`                                                                     | field             | An explicit index, usually inferred                                                                                                                                                                                                      |
+| `@storedAs(type:)`                                                                                         | custom scalar     | How a custom scalar is stored (`STRING`, `INT`, `FLOAT`, `BOOLEAN`, `DATETIME`, `DATE`); its SDL description is what clients see, whatever implementation `scalars` passes                                                               |
 | `@relationship(type:, direction:, properties:, queryDirection:, onDelete:, nestedOperations:, aggregate:)` | field             | An edge to a `@node` type, interface or union. `queryDirection: UNDIRECTED` reads both ways; `onDelete: DETACH \| CASCADE \| RESTRICT`; `nestedOperations` lists the nested writes inputs offer; `aggregate: false` drops its aggregates |
 | `@declareRelationship`                                                                                     | interface field   | Every implementation declares this relationship (type and direction may differ); select it on the interface                                                                                                                              |
 | `@relationshipProperties`                                                                                  | type              | Properties on a relationship type                                                                                                                                                                                                        |
 | `@alias(property:)`                                                                                        | field             | API name differs from the stored property                                                                                                                                                                                                |
 | `@private`                                                                                                 | field             | Stored, never exposed                                                                                                                                                                                                                    |
-| `@readonly`                                                                                                | field             | Exposed, never client-settable                                                                                                                                                                                                           |
-| `@settable(onCreate:, onUpdate:)`                                                                          | field             | Which mutations may set it, e.g. set once on create                                                                                                                                                                                      |
+| `@readonly`                                                                                                | field             | Exposed, never client-settable; on a relationship, absent from create and update inputs                                                                                                                                                  |
+| `@settable(onCreate:, onUpdate:)`                                                                          | field             | Which mutations may set it, e.g. set once on create; on a relationship, whether the inputs offer it (an upsert of an existing node keeps it)                                                                                             |
 | `@selectable(onRead:, onAggregate:)`                                                                       | field             | `onRead: false` makes a field write-only                                                                                                                                                                                                 |
-| `@default(value:)`                                                                                         | field             | Stored on create when the input omits it                                                                                                                                                                                                 |
-| `@timestamp(operations: [CREATE, UPDATE])`                                                                 | field             | Set to the current time; never client-settable                                                                                                                                                                                           |
+| `@default(value:)`                                                                                         | field             | Stored on create when the input omits it; on a relationship property, when the relationship is created                                                                                                                                   |
+| `@timestamp(operations: [CREATE, UPDATE])`                                                                 | field             | Set to the current time; never client-settable. On a relationship property: CREATE when the relationship is created, UPDATE on edge updates and re-connects that set properties                                                          |
 | `@populatedBy(callback:, operations:)`                                                                     | field             | Computed by a named callback on write                                                                                                                                                                                                    |
 | `@cardinality(max:)`                                                                                       | list relationship | Declared fan-out, for cost estimates                                                                                                                                                                                                     |
 | `@cypher(statement:, columnName:)`                                                                         | field             | A field backed by a Cypher statement. Returns scalars, `@node` types, interfaces or unions over them, or object types without `@node` (read from a map)                                                                                  |
@@ -375,7 +376,10 @@ mutation {
 - **Updates** set fields (`null` removes one) and relationships (`connect`,
   `create`, `disconnect`, and `update` of connected nodes and relationship
   properties in place). Connecting an already-connected pair keeps one
-  relationship and updates its properties.
+  relationship and sets the properties the input gives; the others,
+  `@default`s included, keep their values. Defaults apply when a
+  relationship is created. Re-connecting a single relationship to its
+  current target keeps that relationship.
 - **`adjust`** applies math (`add`, `subtract`, `multiply`, `divide`) and
   list (`push`, `pop`, `remove`) operators to the stored value atomically;
   a missing number counts as 0 and a missing list as empty.
@@ -385,7 +389,14 @@ mutation {
   is an error that writes nothing, and an empty `where` is refused.
 - **`upsertFestivals`** creates the inputs whose key is new and updates the
   rest; fields required on create are required only for new keys. A key the
-  caller may not see reads as taken.
+  caller may not see is never updated, and never reported as taken: it gets
+  the answer a free key would (see below).
+- **Creating under a hidden key** (`createFestivals`, `upsertFestivals`, a
+  nested `create`) answers as if the key were free: whatever error the free
+  key would get, and where it would be created, `FORBIDDEN` ("not allowed to
+  create"), never a `CONSTRAINT_VIOLATION` that would confirm the key
+  exists. A key held by a node the caller can read is still reported as
+  taken. See `docs/design/graphql-threat-model.md`.
 - **Deletes** follow `onDelete`: `DETACH` (default) removes the
   relationships, `CASCADE` deletes what the field reaches (checking the
   caller may delete each node), `RESTRICT` refuses while related nodes
@@ -418,6 +429,14 @@ bounded like bulk deletes and following `onDelete`. `limit` defaults to
 writes in the inputs, and `aggregate: false` removes the relationship's
 aggregates and aggregate filter.
 
+An input left with no field is left out, with what would take it: a
+relationship without settable properties has no `edge` input, and a type
+with nothing settable on update (no settable field, no relationship with
+a nested write) has no update mutations; the model warns when
+`@mutation(operations: [UPDATE])` asked for them. A generated schema
+graphql-js would reject is a `ModelError` from `getSchema()`, never an
+error on every request.
+
 ## Search
 
 ```graphql
@@ -491,7 +510,10 @@ type Mutation {
 ```
 
 `this` is the parent node; arguments are `$parameters`; `$jwt` holds the
-request's claims. `columnName` is inferred from `RETURN x` or `RETURN … AS x`.
+request's claims. `columnName` is inferred when the statement's last
+top-level `RETURN` has one item, `RETURN x` or `RETURN … AS x` (commas
+inside calls, lists, maps and `CALL { }` do not count); with several
+items, set it.
 Fields returning `@node` types are projected with the selection like any
 other node, and read filters apply to them.
 
@@ -578,6 +600,12 @@ type Post
   `"$context.path"` strings values from the GraphQL context. `jwt` tests
   claims (`eq`, `in`, `includes`, `contains`, `startsWith`, `endsWith`,
   `lt`, `lte`, `gt`, `gte`, `exists`).
+- Inside a longer string, write `${jwt.path}` or `${context.path}`:
+  `key: { startsWith: "${jwt.sub}:" }` confines a user to keys that begin
+  with their `sub` and `:`. The claim must be a string, number or boolean;
+  otherwise the rule denies. Pick a separator no `sub` contains: with `-`,
+  user `a` could take `a-b-…`, the key space of user `a-b`. See
+  [docs/design/graphql-claim-interpolation.md](../../docs/design/graphql-claim-interpolation.md).
 - **Claim tests run in JavaScript at compile time**, so an admin's
   statement carries no filter at all. Statements stay specialised and
   index-friendly.
@@ -588,7 +616,9 @@ type Post
 - `filter` rules (any passing rule grants) make other nodes invisible:
   in lists, lookups, counts, aggregates, search, nested relationships,
   relationship filters, subscriptions, and as targets of updates, deletes
-  and connects. Filter rules for `CREATE_RELATIONSHIP` and
+  and connects. A node the same mutation creates is not hidden from its
+  own connects, so a filter that depends on the new relationship (a
+  request visible to its sender) does not block a nested create. Filter rules for `CREATE_RELATIONSHIP` and
   `DELETE_RELATIONSHIP` guard both ends of connects and disconnects.
 - `validate` rules fail the request with `FORBIDDEN`: `BEFORE` an update or
   delete, `AFTER` a create or update (rolling it back), and for `READ`: on
@@ -597,8 +627,18 @@ type Post
 - Field-level `@authorization(validate:)` guards one field: reading it on a
   row that fails is `FORBIDDEN`, filtering by it only matches rows that
   pass, sorting or aggregating by it is refused, and writing it checks the
-  rule. Field-level `@authentication` also guards filtering, sorting and
-  aggregating on the field.
+  rule. A write is what the input sets: a create that leaves the field out
+  is not checked against it, even when `@default` or `@populatedBy` fills
+  it, so a CREATE rule can keep a `verified: Boolean! @default(value: false)`
+  settable by admins only while anyone creates the node. Field-level
+  `@authentication` also guards filtering, sorting and aggregating on the
+  field.
+- Reading a guarded field is checked per row, token or not: without the
+  token a rule needs, each row reads the field as `UNAUTHENTICATED`. The
+  statement has the same shape either way, so `compile()`, `explain()`,
+  `check()` and `expectSeeks` plan-check such operations without a token;
+  pass `context` (per operation in `check({ operations })`) to compile
+  them as a signed-in caller.
 - `@authentication(operations:, jwt:)` covers `READ`, `CREATE`, `UPDATE`,
   `DELETE`, `CREATE_RELATIONSHIP`, `DELETE_RELATIONSHIP` and `SUBSCRIBE`,
   and may require claims.
@@ -610,6 +650,29 @@ Relationship and `@cypher` fields take field-level `@authorization`
 with READ validate rules: a row failing the rule reads the field as
 `FORBIDDEN`, and filtering through the field applies the rule too.
 
+Relationship properties take field-level `@authentication` and
+`@authorization(validate:)` for `READ`, `CREATE` and `UPDATE`. One
+`@relationshipProperties` type can serve fields on both ends, so these
+rules test claims (`jwt`) only; a `node` part is a model error. Setting
+the property on connect or nested create checks `CREATE` for a new
+relationship and `UPDATE` for one that already exists; `update: { edge }`
+checks `UPDATE`. A request the READ rules refuse reads the property as
+`FORBIDDEN` and cannot filter, sort or aggregate by it.
+
+```graphql
+type Membership @relationshipProperties {
+  role: String
+    @authorization(
+      validate: [
+        {
+          operations: [CREATE, UPDATE]
+          where: { jwt: { roles: { includes: "admin" } } }
+        }
+      ]
+    )
+}
+```
+
 ## The smart layer
 
 **S1: indexes from the API.** `requirements()` derives every constraint and
@@ -632,13 +695,19 @@ index the API needs, with the reason for each:
 **S2: plans are checked.** Every compiled statement records the access path
 it was written for. `lora.explain(query, variables)` plans each statement and
 reports a label scan where a seek was expected, a mutating plan behind a
-read, or result columns that do not match. `lora.check({ operations })`
-runs this over your operations; the CLI does it in CI.
+read, or result columns that do not match. The access path checked is the
+root field's own, outside every `CALL { }`: a label scan inside one (a
+`@cypher` statement's `MATCH`) is reported as a lint-level `notes` entry,
+not blamed on the root. `lora.check({ operations })` runs this over your
+operations; the CLI does it in CI.
 
 **S3: compile once.** `lora.persist({ id: source })` parses and validates
 persisted operations at startup, and `lora.execute({ id, variables, context })`
 runs them with no parsing or validation. Ad hoc documents passed to
-`execute({ source })` are cached too. Translation itself takes about 0.13 ms
+`execute({ source })` are cached too. A subscription runs the same way with
+`lora.subscribe({ id | source, variables, context })`, which returns an
+async iterable of results (end it with `context.signal`); `execute()` answers
+a subscription with an error pointing there. Translation itself takes about 0.13 ms
 for a nested page, and statement text depends only on the shape of the
 input, so LoraDB's own plan cache is hit for every repeat.
 
@@ -725,10 +794,14 @@ claims cost one visibility query and one node read per write.
 
 By default subscriptions see the writes this instance makes. With
 `changeFeed: true` (lora-node), subscriptions and `changes()` are fed by
-the engine's committed change feed instead: every write, whichever path or
-process made it (hand-written Cypher, `@cypher` mutations, imports), in
-commit order, with relationship ends resolved to their `@key`s. A consumer
-that falls behind resumes from its last position. `onWrite` still reports
+the engine's committed change feed instead: every committed write to the
+database, whichever path in the owning process made it (hand-written
+Cypher, `@cypher` mutations, imports, other instances), in commit order,
+with relationship ends resolved to their `@key`s. A database directory is
+open in one process at a time, so this is not a cross-process feed. If the
+reader falls behind the engine it resumes from its last position, which is
+kept in memory: a new instance starts at the current commit and does not
+replay earlier writes. `onWrite` still reports
 this instance's mutations, and `previousState` needs them: the feed carries
 the state after the write. Call `lora.close()` to stop the feed.
 
@@ -775,6 +848,10 @@ files, and exits non-zero on any finding. It is the CI gate. Options:
 
 - `--variables vars.json`: variables per operation name, instead of
   sample values for the required ones.
+- `--context ctx.json`: the GraphQL context per operation name (`*` for
+  the rest), e.g. `{ "*": { "jwt": { "sub": "u1" } } }`, so rules compile
+  as they do for a signed-in caller. `check({ operations })` takes the
+  same as `context` on each operation.
 - `--baseline plans.json`: the operators of every statement; a plan that
   differs fails, so plan changes show up in review (`--update-baseline`
   accepts them; a missing file is written).
@@ -857,7 +934,7 @@ which only the Node binding has, so the WASM binding serves reads.
 | `maskErrors`                 | production    | Clients get `DATABASE_ERROR` and an `id` only       |
 | `onError`                    |               | Receives each database error's detail and `id`      |
 | `guards`                     | see below     | Document limits; `false` turns them off             |
-| `persistedOnly`              | false         | `execute()` runs persisted operations only          |
+| `persistedOnly`              | false         | `execute()`, `subscribe()` run persisted ops only   |
 | `budget`                     |               | Cost limit per request, from the context            |
 | `onCost`                     |               | Each root field's estimate, total and limit         |
 | `onStatementEnd`             |               | Duration, rows and error of every statement call    |
@@ -866,15 +943,16 @@ which only the Node binding has, so the WASM binding serves reads.
 
 Errors carry `extensions.code`: `BAD_USER_INPUT`, `INVALID_CURSOR`,
 `LIMIT_EXCEEDED`, `COST_EXCEEDED`, `UNAUTHENTICATED`, `FORBIDDEN`,
-`NOT_FOUND`, `CONSTRAINT_VIOLATION` (with `type` and `field`) and
-`DATABASE_ERROR` (with an `id`, also given to `onError`). An invalid SDL
+`NOT_FOUND`, `CONSTRAINT_VIOLATION` (with `type` and `field`),
+`DATABASE_ERROR` (with an `id`, also given to `onError`) and
+`PERSISTED_QUERY_ONLY` (`execute()` or `subscribe()` got a document under `persistedOnly`). An invalid SDL
 throws one `ModelError` listing every problem, each located by type and
 field.
 
 ### Security defaults
 
 `maxCost` bounds the rows an operation touches; the document guards bound
-the document before that. `execute()` and `persist()` apply them, and
+the document before that. `execute()`, `subscribe()` and `persist()` apply them, and
 `lora.validationRules()` / `lora.envelopPlugin()` bring them to any other
 server (GraphQL Yoga takes the plugin as is):
 
@@ -929,7 +1007,8 @@ exceeds the budget; every plan report carries `estimatedRows` either way.
 
 `@loradb/lora-graphql` is released in lockstep with `@loradb/lora-node`:
 version X.Y.Z declares `"@loradb/lora-node": "^X.Y.Z"` as its peer and is
-tested against that binding. Upgrade both together.
+tested against that binding. Upgrade both together. `graphql` 16 and 17 are
+both supported peers; the test suite runs on each.
 
 ## Translation rules
 
@@ -943,7 +1022,7 @@ Measured on LoraDB 0.15 over 20 000 festivals and 100 000 relationships
 | Ordered by an always-present string: `WHERE s >= ""`                                 | The planner walks the index in order and stops at the limit: 0.03 ms instead of 7 ms |
 | Mutation statements seek the key in their own `MATCH`, then expand                   | The plan no longer depends on the optimizer finding the seek: 0.06 ms per connect    |
 | A relationship filter naming a key starts from that node                             | 0.07 ms instead of 9.3 ms                                                            |
-| Keyset predicates written out, led by `sortKey >= $v` on non-null keys               | `[a, b] > $list` silently matches nothing; the lead bound gets a range scan          |
+| Keyset predicates written out, led by `sortKey >= $v` on non-null keys               | The lead bound gets a range scan; `[a, b] > $list` does not                          |
 | Lists sort by the requested fields only; connections add a unique tie-breaker        | Two sort keys cannot stream from an index                                            |
 | Every value a parameter; every identifier from the model, escaped                    | No injection, stable statement text                                                  |
 | Absent filters left out, never `($p IS NULL OR …)`                                   | Keeps the predicate visible to the planner                                           |
@@ -974,8 +1053,9 @@ Fixed in the engine and no longer worked around: labels after the first
 node of a `MATCH`, early `LIMIT` under a deadline or in a transaction,
 `MERGE` with a bound end node (connect is one `MERGE`), writes in
 `CALL { }`, temporal RANGE indexes (inferred again for temporal fields),
-`x IN $list` seeks, `null` values in property maps, and existence checks
-before a following `SET`.
+`x IN $list` seeks, `null` values in property maps, existence checks
+before a following `SET`, list comparison (`[a, b] > $list`) and
+`first()`.
 
 | Behaviour                                                                                | Workaround                                                                |
 | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
@@ -983,12 +1063,12 @@ before a following `SET`.
 | `max`, `sum` and `avg` over durations are wrong                                          | Duration aggregates are folded with `reduce`                              |
 | Integer division returns a float; negative list slices (`l[..-1]`) return `[]`           | `toInteger(a / b)` for Int fields; `l[..size(l) - n]`                     |
 | `COUNT { … RETURN DISTINCT x }`, `EXISTS { }` and `UNION` inside `CALL` do not parse     | `reduce` for distinct counts; comprehensions; per-member subqueries       |
-| `[a, b] > $list` matches nothing; `first()` is unknown                                   | See translation rules                                                     |
 
 ## Development
 
 ```sh
 yarn test       # vitest: model, TCK snapshots, integration, auth, mutations, CLI
+yarn test:graphql17  # the same suite on graphql 17
 yarn bench      # latency on a seeded graph
 yarn typecheck && yarn lint && yarn build
 ```

package/dist/analyze/plans.d.ts

@@ -17,6 +17,12 @@ export interface PlanReport {
      */
     estimatedRows: number | null;
     findings: PlanFinding[];
+    /**
+     * Lint-level observations that do not fail a check: label scans inside
+     * a `CALL { }` body, such as a `@cypher` statement's own access path.
+     * They are the statement's author's to review, not the root field's.
+     */
+    notes: PlanFinding[];
 }
 export declare function checkPlans(driver: LoraDriver, compiled: CompiledRead, options?: {
     rowBudget?: number;