@segmentstream-cloud/ontology 0.24.0 → 0.24.1

package/README.md

@@ -500,6 +500,22 @@ usage error.
 `ontology/index.ts`, migrates the workspace database and deploys the service under
 `/api/ontology`. A failure stops the deployment and keeps the running version.
 
+## Development tests
+
+`npm test --workspace @segmentstream-cloud/ontology` runs the ordinary suite with
+embedded PGlite. Authentication contention tests require separate PostgreSQL
+backends and run against a local disposable PostgreSQL server:
+
+```sh
+ONTOLOGY_TEST_ADMIN_URL=postgresql://postgres@127.0.0.1:5432/postgres \
+  npm run test:postgres --workspace @segmentstream-cloud/ontology
+```
+
+The test fixture accepts only a localhost `postgres` admin connection to the
+`postgres` database. It creates a randomly named test database, applies the example
+ontology, and drops that database on completion. Repository CI and the SDK release
+gate run this suite with PostgreSQL 17.
+
 ## License
 
 Apache-2.0

package/dist/runtime/principals.d.ts

@@ -46,7 +46,8 @@ export declare const SIGN_IN_RECORD_INTERVAL_MS: number;
  * is linked by email when someone invited them; a person nobody invited is rejected as
  * `not_invited` under the `invited` policy and becomes a member holding only `member` under
  * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
- * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. Inactive users are rejected.
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
  */
 export declare function resolvePrincipalByIdentity(ontology: Ontology, claims: IdentityClaims): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
 /** Resolve the workspace's stable keyless pipeline service, without customer roles or sign-in. */

package/dist/runtime/principals.js

@@ -15,7 +15,7 @@ import { beginReplicationWrite } from "../replication/transaction.js";
 import { User } from "../user.js";
 import { MemberNotFound, PrincipalRejected, UnknownRole } from "./errors.js";
 import { isRecordId } from "./records.js";
-import { makeOntologyRuntime } from "./sql-runtime.js";
+import { makeOntologyRuntime, makePrincipalUserWriter, } from "./sql-runtime.js";
 /** API keys are `ssk_<key id>.<secret>`. */
 export const API_KEY_PREFIX = "ssk_";
 /**
@@ -107,93 +107,116 @@ function userRow(record) {
     return decodeUser({ id: record.id, kind: record.kind, active: record.active });
 }
 /**
- * Finds, links or creates the member's user, in one transaction, and records the sign-in on it. A
+ * Finds the member's user without locking. Links or creates it transactionally when needed. A
  * user linked to this identity is found; else a member invited with the same email is linked; else
  * the ontology's sign-in policy decides: `invited` turns the person away, `open` creates a member.
  */
 function signIn(ontology, sql, claims) {
-    const runtime = platformRuntime(ontology, sql, "user.sign_in");
+    const runtime = makeOntologyRuntime(ontology, sql);
+    const writer = makePrincipalUserWriter(ontology, sql, {
+        action: "user.sign_in",
+        actionId: randomUUID(),
+    });
     const claimedEmail = claims.email?.trim().toLowerCase();
     const email = claimedEmail !== undefined && EMAIL_PATTERN.test(claimedEmail) ? claimedEmail : undefined;
-    return sql
-        .withTransaction(Effect.gen(function* () {
-        yield* beginReplicationWrite(sql);
-        const now = new Date();
-        const signedIn = { last_sign_in_at: now.toISOString() };
-        const [linked] = yield* runtime.find({
-            entity: "user",
-            options: {
-                where: {
-                    identity_provider: claims.identityProvider,
-                    identity_subject: claims.identitySubject,
-                },
-                limit: 1,
-                forUpdate: true,
+    const findLinked = (forUpdate = false) => runtime.find({
+        entity: "user",
+        options: {
+            where: {
+                identity_provider: claims.identityProvider,
+                identity_subject: claims.identitySubject,
             },
-        });
-        if (linked !== undefined) {
-            // An inactive user is turned away, which is not a sign-in to record.
-            if (linked.active !== true || !signInDue(linked.last_sign_in_at, now)) {
-                return userRow(linked);
+            limit: 1,
+            forUpdate,
+        },
+    });
+    const member = (record) => record.kind === "member"
+        ? Effect.succeed(userRow(record))
+        : Effect.fail(new PrincipalRejected({
+            reason: "identity_conflict",
+            message: "This identity belongs to a service, not a member.",
+        }));
+    return Effect.gen(function* () {
+        const [known] = yield* findLinked();
+        if (known !== undefined) {
+            const user = yield* member(known);
+            // Ordinary authentication is read-only. Optional bookkeeping must never queue behind a
+            // business transaction holding a User key or row lock; a later request can record it.
+            if (!user.active || !writer.recordsSignIn || !signInDue(known.last_sign_in_at, new Date())) {
+                return user;
             }
-            const returning = yield* runtime.update({
-                entity: "user",
-                id: linked.id,
-                values: signedIn,
-            });
-            return userRow(returning);
+            return yield* sql.withTransaction(Effect.gen(function* () {
+                const [locked] = yield* sql.unsafe(`SELECT "id" FROM "${USER_TABLE}" WHERE "id" = $1::uuid FOR UPDATE SKIP LOCKED`, [user.id]);
+                if (locked === undefined) {
+                    return user;
+                }
+                const current = yield* runtime.get({ entity: "user", id: user.id });
+                const principal = yield* member(current);
+                const now = new Date();
+                if (principal.active && signInDue(current.last_sign_in_at, now)) {
+                    yield* writer.update(user.id, { last_sign_in_at: now.toISOString() });
+                }
+                return principal;
+            }));
         }
-        const [invited] = email === undefined
-            ? []
-            : yield* runtime.find({
-                entity: "user",
-                options: { where: { email }, limit: 1, forUpdate: true },
-            });
-        if (invited !== undefined) {
-            if (invited.kind !== "member" || invited.identity_subject !== null) {
-                return yield* new PrincipalRejected({
-                    reason: "identity_conflict",
-                    message: "Another user already has this email.",
-                });
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            const now = new Date();
+            const signedIn = writer.recordsSignIn ? { last_sign_in_at: now.toISOString() } : {};
+            const [linked] = yield* findLinked(true);
+            if (linked !== undefined) {
+                return yield* member(linked);
             }
-            const linkedUser = yield* runtime.update({
-                entity: "user",
-                id: invited.id,
-                values: {
+            const [invited] = email === undefined
+                ? []
+                : yield* runtime.find({
+                    entity: "user",
+                    options: { where: { email }, limit: 1, forUpdate: true },
+                });
+            if (invited !== undefined) {
+                // A concurrent first sign-in may have linked this invitation while this transaction
+                // waited for its row. Accept the exact identity; another identity still conflicts.
+                if (invited.identity_provider === claims.identityProvider &&
+                    invited.identity_subject === claims.identitySubject) {
+                    return yield* member(invited);
+                }
+                if (invited.kind !== "member" || invited.identity_subject !== null) {
+                    return yield* new PrincipalRejected({
+                        reason: "identity_conflict",
+                        message: "Another user already has this email.",
+                    });
+                }
+                const linkedUser = yield* writer.update(invited.id, {
                     identity_provider: claims.identityProvider,
                     identity_subject: claims.identitySubject,
                     ...(invited.active === true ? signedIn : {}),
-                },
-            });
-            return userRow(linkedUser);
-        }
-        if (ontology.signIn.policy !== "open") {
-            return yield* new PrincipalRejected({
-                reason: "not_invited",
-                message: "No member was invited with this identity or email.",
-            });
-        }
-        const created = yield* runtime.create({
-            entity: "user",
-            values: {
+                });
+                return userRow(linkedUser);
+            }
+            if (ontology.signIn.policy !== "open") {
+                return yield* new PrincipalRejected({
+                    reason: "not_invited",
+                    message: "No member was invited with this identity or email.",
+                });
+            }
+            const created = yield* writer.create({
                 name: claims.name?.trim() || email || claims.identitySubject,
                 email: email ?? null,
                 kind: "member",
                 identity_provider: claims.identityProvider,
                 identity_subject: claims.identitySubject,
                 ...signedIn,
-            },
-        });
-        return userRow(created);
-    }))
-        .pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
+            });
+            return userRow(created);
+        }));
+    }).pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
 }
 /**
  * The principal of a member signed in with a verified token. On first sign-in the member's `user`
  * is linked by email when someone invited them; a person nobody invited is rejected as
  * `not_invited` under the `invited` policy and becomes a member holding only `member` under
  * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
- * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. Inactive users are rejected.
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
  */
 export function resolvePrincipalByIdentity(ontology, claims) {
     return Effect.gen(function* () {

package/dist/runtime/sql-runtime.d.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
-import { type NotFound } from "../errors.js";
+import { Conflict, type NotFound } from "../errors.js";
 import type { Ontology } from "../ontology.js";
 import type { Query, QueryResult } from "../query.js";
-import type { OntologyRuntimeService, StoredRecord } from "../runtime.js";
+import type { OntologyRuntimeService, StoredRecord, StoredValues } from "../runtime.js";
 import { InvalidQuery } from "./errors.js";
 import type { Edit, HistoryEntry, HistoryScope } from "./history.js";
 /**
@@ -39,6 +39,16 @@ export interface SqlOntologyRuntime extends OntologyRuntimeService {
         readonly limit?: number;
     }) => Effect.Effect<QueryResult<HistoryEntry>, InvalidQuery>;
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export declare function makePrincipalUserWriter(ontology: Ontology, sql: SqlClient.SqlClient, scope: Pick<HistoryScope, "action" | "actionId">): {
+    recordsSignIn: boolean;
+    create: (values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+    update: (id: string, values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+};
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares

package/dist/runtime/sql-runtime.js

@@ -2,6 +2,8 @@ import { Effect } from "effect";
 import { beginReplicationWrite } from "../replication/transaction.js";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { Conflict } from "../errors.js";
+import { toSnakeCase } from "../names.js";
+import { User } from "../user.js";
 import { InvalidQuery, WriteOutsideAction } from "./errors.js";
 import { entityModel, ontologyModel } from "./model.js";
 import { loadRecord, notFound, readHistory, relatedCondition, runQuery, validateQuery, } from "./reads.js";
@@ -41,6 +43,37 @@ function uniqueConflict(entity, error) {
             message: `A ${label} with this ${field.name} already exists.`,
         }));
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export function makePrincipalUserWriter(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const user = entityModel(model, User.name);
+    const allowed = new Set(Object.keys(User.definition.properties).map(toSnakeCase));
+    const client = sql.withoutTransforms();
+    const context = () => ({
+        model,
+        scope: { action: scope.action, actionId: scope.actionId, principalId: null },
+        edits: [],
+        run: (text, params) => client.unsafe(text, params.values),
+    });
+    const write = (values, operation) => Effect.suspend(() => {
+        if (!user.manifest.builtIn ||
+            Object.keys(values).some((name) => !allowed.has(name) || user.fieldsByName.get(name)?.source !== "property")) {
+            return Effect.die(new Error("Principal writes accept only built-in User properties."));
+        }
+        return sql
+            .withTransaction(operation())
+            .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(user, error)));
+    });
+    return {
+        recordsSignIn: user.fieldsByName.has("last_sign_in_at"),
+        create: (values) => write(values, () => createRecord(context(), user, values)),
+        update: (id, values) => write(values, () => updateRecord(context(), user, id, values)),
+    };
+}
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -44,6 +44,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint src tests --config ../../eslint.config.mjs",
     "test": "vitest run",
+    "test:postgres": "vitest run --config vitest.postgres.config.ts",
     "prepack": "npm run build"
   },
   "dependencies": {