Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,103 @@
|
||||
/**
|
||||
* Hocuspocus database extension persisting Y.js docs to Postgres
|
||||
* (`CollabDoc` table).
|
||||
*
|
||||
* `fetch({ documentName })` → Loads BLOB from Postgres on connect; returns
|
||||
* `null` when no row exists (Hocuspocus then
|
||||
* initialises a fresh in-memory Y.Doc).
|
||||
* `store({ documentName, state })` → Upserts the BLOB, bumps `version`,
|
||||
* refreshes `lastUpdatedAt`. Debounced by
|
||||
* Hocuspocus per the server-level
|
||||
* `debounce` / `maxDebounce` settings.
|
||||
*
|
||||
* The DocumentName is parsed via `parseDocumentName()` (see auth.ts) and is
|
||||
* authoritative for the `(tenantId, resourceType, resourceId)` triple. Auth
|
||||
* has already verified that the connection has access to this triple; here
|
||||
* we just persist the bytes.
|
||||
*
|
||||
* Refs: docs/improvement-plan/05-business-features/realtime-collab.md
|
||||
*/
|
||||
import { Database } from "@hocuspocus/extension-database";
|
||||
import type { Extension } from "@hocuspocus/server";
|
||||
import type { DbClient } from "@toolctrl/db/client.server";
|
||||
|
||||
import { parseDocumentName } from "./auth.js";
|
||||
|
||||
export type DatabaseExtensionDeps = {
|
||||
/** Prisma client (write-able). */
|
||||
readonly db: Pick<DbClient, "collabDoc">;
|
||||
/** Maximum bytes we will store per doc — protects from runaway state-bloat. */
|
||||
readonly maxPayloadBytes: number;
|
||||
/**
|
||||
* Optional clock hook for deterministic tests. Defaults to `() => new Date()`.
|
||||
*/
|
||||
readonly clock?: () => Date;
|
||||
};
|
||||
|
||||
/**
|
||||
* Internal `fetch` implementation — exported for unit-testing.
|
||||
*/
|
||||
export async function fetchCollabDoc(documentName: string, deps: DatabaseExtensionDeps): Promise<Uint8Array | null> {
|
||||
const parsed = parseDocumentName(documentName);
|
||||
if (!parsed) return null;
|
||||
const row = await deps.db.collabDoc.findUnique({
|
||||
where: {
|
||||
tenantId_resourceType_resourceId: {
|
||||
tenantId: parsed.tenantId,
|
||||
resourceType: parsed.resourceType,
|
||||
resourceId: parsed.resourceId,
|
||||
},
|
||||
},
|
||||
select: { ydocState: true },
|
||||
});
|
||||
if (!row) return null;
|
||||
// Prisma returns `Buffer` for Bytes columns — wrap to Uint8Array for Y.js.
|
||||
return new Uint8Array(row.ydocState);
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal `store` implementation — exported for unit-testing.
|
||||
*/
|
||||
export async function storeCollabDoc(documentName: string, state: Uint8Array, deps: DatabaseExtensionDeps): Promise<void> {
|
||||
const parsed = parseDocumentName(documentName);
|
||||
if (!parsed) return;
|
||||
if (state.byteLength > deps.maxPayloadBytes) {
|
||||
throw new Error(
|
||||
`hocuspocus: refusing to persist Y.js state of ${state.byteLength} bytes — exceeds HOCUSPOCUS_MAX_PAYLOAD_BYTES=${deps.maxPayloadBytes}`,
|
||||
);
|
||||
}
|
||||
const now = (deps.clock ?? (() => new Date()))();
|
||||
const buffer = Buffer.from(state);
|
||||
await deps.db.collabDoc.upsert({
|
||||
where: {
|
||||
tenantId_resourceType_resourceId: {
|
||||
tenantId: parsed.tenantId,
|
||||
resourceType: parsed.resourceType,
|
||||
resourceId: parsed.resourceId,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId: parsed.tenantId,
|
||||
resourceType: parsed.resourceType,
|
||||
resourceId: parsed.resourceId,
|
||||
ydocState: buffer,
|
||||
version: 1,
|
||||
lastUpdatedAt: now,
|
||||
},
|
||||
update: {
|
||||
ydocState: buffer,
|
||||
version: { increment: 1 },
|
||||
lastUpdatedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the Hocuspocus database extension wired to the Prisma client.
|
||||
*/
|
||||
export function createDatabaseExtension(deps: DatabaseExtensionDeps): Extension {
|
||||
return new Database({
|
||||
fetch: async ({ documentName }) => fetchCollabDoc(documentName, deps),
|
||||
store: async ({ documentName, state }) => storeCollabDoc(documentName, state, deps),
|
||||
}) as unknown as Extension;
|
||||
}
|
||||
Reference in new issue
Block a user