Some checks failed
CultMesh QUIC native / Build win32-x64 (pull_request) Has been skipped
CultMesh QUIC native / Build linux-x64 (pull_request) Has been skipped
CultMesh QUIC native / Release native binaries (pull_request) Has been skipped
CultMesh portability and performance / ubuntu-latest one-command multiplayer onboarding (pull_request) Failing after 41s
CultNet cross-runtime interop / C# / TypeScript / Rust / Python / Kotlin (pull_request) Has been cancelled
CultMesh QUIC native / Verify committed binaries match SHA256SUMS (pull_request) Has been cancelled
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Failing after 5m58s
CultMesh portability and performance / windows-latest one-command multiplayer onboarding (pull_request) Has been cancelled
CultMesh portability and performance / windows-latest reactive semantics and leases (pull_request) Has been cancelled
MessagePack encodes undefined as nil, and the peer rejects a document whose sourceRuntimeId/sourceAgentId/sourceRole/tags are nil. Omit absent keys; test that the encoded message carries none. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
410 lines
14 KiB
TypeScript
410 lines
14 KiB
TypeScript
import type {
|
|
AnyCultCacheDocumentDefinition,
|
|
CultCache,
|
|
CultCacheDocumentValue,
|
|
CultCacheEnvelope,
|
|
} from "@gamecult/cultcache-ts";
|
|
import {
|
|
SchemaConflictError,
|
|
decodeDocumentPayload,
|
|
documentPayloadBytes,
|
|
documentPayloadFromBytes,
|
|
encodeDocumentPayload,
|
|
schemaIdentityOf,
|
|
} from "@gamecult/cultcache-ts";
|
|
|
|
import {
|
|
type CultNetDocumentDeleteMessage,
|
|
type CultNetDocumentPutMessage,
|
|
type CultNetDocumentPutRawMessage,
|
|
type CultNetDocumentRecord,
|
|
type CultNetRawDocumentRecord,
|
|
type CultNetSnapshotRequestMessage,
|
|
type CultNetSnapshotResponseMessage,
|
|
type CultNetSnapshotResponseRawMessage,
|
|
} from "./contracts";
|
|
|
|
export interface CultNetDocumentBinding<
|
|
TDefinition extends AnyCultCacheDocumentDefinition = AnyCultCacheDocumentDefinition,
|
|
> {
|
|
definition: TDefinition;
|
|
payloadSchemaVersion?:
|
|
| string
|
|
| ((value: CultCacheDocumentValue<TDefinition>) => string | undefined);
|
|
}
|
|
|
|
export function defineCultNetDocumentBinding<
|
|
TDefinition extends AnyCultCacheDocumentDefinition,
|
|
>(
|
|
binding: CultNetDocumentBinding<TDefinition>,
|
|
): CultNetDocumentBinding<TDefinition> {
|
|
return Object.freeze({ ...binding });
|
|
}
|
|
|
|
export class CultNetDocumentRegistry {
|
|
readonly #bindings = new Map<string, CultNetDocumentBinding>();
|
|
// The binding that owns each schema id, and every binding listing an id as compatible, in registration order.
|
|
readonly #owners = new Map<string, CultNetDocumentBinding>();
|
|
readonly #listers = new Map<string, CultNetDocumentBinding[]>();
|
|
|
|
constructor(bindings: Iterable<CultNetDocumentBinding> = []) {
|
|
for (const binding of bindings) {
|
|
this.register(binding);
|
|
}
|
|
}
|
|
|
|
register(binding: CultNetDocumentBinding): this {
|
|
// One definition owns a type, a schema id and a schema name, derived as CultCache derives them. Another definition
|
|
// claiming any of them is refused, so a schema never resolves to two types.
|
|
const identity = schemaIdentityOf(binding.definition);
|
|
for (const holder of this.#bindings.values()) {
|
|
if (holder.definition === binding.definition) {
|
|
continue;
|
|
}
|
|
const held = schemaIdentityOf(holder.definition);
|
|
const claimed =
|
|
holder.definition.type === binding.definition.type ? `type "${binding.definition.type}"`
|
|
: held.schemaId === identity.schemaId ? `schema id "${identity.schemaId}"`
|
|
: held.schemaName === identity.schemaName ? `schema name "${identity.schemaName}"`
|
|
: undefined;
|
|
if (claimed) {
|
|
throw new SchemaConflictError(identity.schemaId, [held.schemaName, identity.schemaName], "",
|
|
`CultNet ${claimed} is already bound to type "${holder.definition.type}"; type "${binding.definition.type}" (schema id "${identity.schemaId}") cannot also be bound.`);
|
|
}
|
|
}
|
|
this.#bindings.set(binding.definition.type, binding);
|
|
this.#owners.set(identity.schemaId, binding);
|
|
for (const schemaId of identity.compatibleSchemaIds) {
|
|
const listers = this.#listers.get(schemaId) ?? [];
|
|
if (schemaId !== identity.schemaId && !listers.some(lister => lister.definition === binding.definition)) {
|
|
this.#listers.set(schemaId, [...listers, binding]);
|
|
}
|
|
}
|
|
return this;
|
|
}
|
|
|
|
get(documentType: string): CultNetDocumentBinding | undefined {
|
|
return this.#bindings.get(documentType);
|
|
}
|
|
|
|
// The binding a record under this schema id belongs to: the id's owner, else the one binding that lists it as
|
|
// compatible. An id nothing declares resolves to nothing. An id that several bindings list and none owns is refused,
|
|
// as the cache refuses it, whatever order the bindings were registered in.
|
|
getBySchemaId(schemaId: string): CultNetDocumentBinding | undefined {
|
|
const owner = this.#owners.get(schemaId);
|
|
if (owner) {
|
|
return owner;
|
|
}
|
|
const listers = this.#listers.get(schemaId) ?? [];
|
|
if (listers.length > 1) {
|
|
const types = listers.map(lister => lister.definition.type).sort();
|
|
throw new SchemaConflictError(schemaId, listers.map(lister => schemaIdentityOf(lister.definition).schemaName).sort(), "",
|
|
`CultNet schema id "${schemaId}" is owned by no bound type and declared compatible by several (${types.join(", ")}), ` +
|
|
"so it resolves to none. Bind the type that owns the id, or declare it on one type.");
|
|
}
|
|
return listers[0];
|
|
}
|
|
|
|
createDocumentPutMessage<TDefinition extends AnyCultCacheDocumentDefinition>(
|
|
binding: CultNetDocumentBinding<TDefinition>,
|
|
messageId: string,
|
|
documentKey: string,
|
|
value: CultCacheDocumentValue<TDefinition>,
|
|
options: {
|
|
storedAt?: string;
|
|
sourceRuntimeId?: string;
|
|
sourceAgentId?: string;
|
|
sourceRole?: string;
|
|
tags?: string[];
|
|
} = {},
|
|
): CultNetDocumentPutMessage<CultCacheDocumentValue<TDefinition>> {
|
|
const parsed = binding.definition.schema.parse(value);
|
|
return {
|
|
schemaVersion: "cultnet.document_put.v0",
|
|
messageId,
|
|
document: {
|
|
schemaId: schemaIdForBinding(binding),
|
|
recordKey: documentKey,
|
|
storedAt: options.storedAt ?? new Date().toISOString(),
|
|
payload: parsed,
|
|
// Absent optional fields must be omitted, not set to undefined: MessagePack encodes undefined as nil and the peer rejects it.
|
|
...(options.sourceRuntimeId !== undefined && { sourceRuntimeId: options.sourceRuntimeId }),
|
|
...(options.sourceAgentId !== undefined && { sourceAgentId: options.sourceAgentId }),
|
|
...(options.sourceRole !== undefined && { sourceRole: options.sourceRole }),
|
|
...(options.tags !== undefined && { tags: options.tags }),
|
|
},
|
|
};
|
|
}
|
|
|
|
createDocumentDeleteMessage(
|
|
messageId: string,
|
|
schemaId: string,
|
|
recordKey: string,
|
|
): CultNetDocumentDeleteMessage {
|
|
return {
|
|
schemaVersion: "cultnet.document_delete.v0",
|
|
messageId,
|
|
schemaId,
|
|
recordKey,
|
|
};
|
|
}
|
|
|
|
createRawDocumentPutMessageFromEnvelope(
|
|
messageId: string,
|
|
envelope: CultCacheEnvelope,
|
|
): CultNetDocumentPutRawMessage {
|
|
return {
|
|
schemaVersion: "cultnet.document_put_raw.v0",
|
|
messageId,
|
|
document: this.#createRawDocumentRecord(envelope),
|
|
};
|
|
}
|
|
|
|
createRawDocumentPutMessage<TDefinition extends AnyCultCacheDocumentDefinition>(
|
|
binding: CultNetDocumentBinding<TDefinition>,
|
|
messageId: string,
|
|
documentKey: string,
|
|
value: CultCacheDocumentValue<TDefinition>,
|
|
options: {
|
|
storedAt?: string;
|
|
sourceRuntimeId?: string;
|
|
sourceAgentId?: string;
|
|
sourceRole?: string;
|
|
tags?: string[];
|
|
} = {},
|
|
): CultNetDocumentPutRawMessage {
|
|
return {
|
|
schemaVersion: "cultnet.document_put_raw.v0",
|
|
messageId,
|
|
document: {
|
|
schemaId: schemaIdForBinding(binding),
|
|
recordKey: documentKey,
|
|
storedAt: options.storedAt ?? new Date().toISOString(),
|
|
payloadEncoding: "messagepack",
|
|
payload: encodeDocumentPayload(binding.definition, value),
|
|
sourceRuntimeId: options.sourceRuntimeId,
|
|
sourceAgentId: options.sourceAgentId,
|
|
sourceRole: options.sourceRole,
|
|
tags: options.tags,
|
|
},
|
|
};
|
|
}
|
|
|
|
createSnapshotResponse(
|
|
cache: CultCache,
|
|
messageId: string,
|
|
filter?: CultNetSnapshotRequestMessage,
|
|
): CultNetSnapshotResponseMessage {
|
|
const requestedSchemaIds = filter?.schemaIds ? new Set(filter.schemaIds) : undefined;
|
|
const requestedKeys = filter?.recordKeys ? new Set(filter.recordKeys) : undefined;
|
|
const documents: CultNetDocumentRecord[] = [];
|
|
|
|
for (const envelope of cache.snapshot()) {
|
|
const binding = this.#requireBinding(envelope.type);
|
|
const schemaId = schemaIdForEnvelope(envelope, binding);
|
|
|
|
if (requestedSchemaIds && !answersTo(schemaId, binding, requestedSchemaIds)) {
|
|
continue;
|
|
}
|
|
|
|
if (requestedKeys && !requestedKeys.has(envelope.key)) {
|
|
continue;
|
|
}
|
|
|
|
const payload = decodeDocumentPayload(binding.definition, envelope.payload);
|
|
documents.push({
|
|
schemaId,
|
|
recordKey: envelope.key,
|
|
storedAt: envelope.storedAt,
|
|
payload,
|
|
});
|
|
}
|
|
|
|
return {
|
|
schemaVersion: "cultnet.snapshot_response.v0",
|
|
messageId,
|
|
documents,
|
|
};
|
|
}
|
|
|
|
createRawSnapshotResponse(
|
|
cache: CultCache,
|
|
messageId: string,
|
|
filter?: CultNetSnapshotRequestMessage,
|
|
): CultNetSnapshotResponseRawMessage {
|
|
const requestedSchemaIds = filter?.schemaIds ? new Set(filter.schemaIds) : undefined;
|
|
const requestedKeys = filter?.recordKeys ? new Set(filter.recordKeys) : undefined;
|
|
const documents: CultNetRawDocumentRecord[] = [];
|
|
|
|
for (const envelope of cache.snapshot()) {
|
|
const binding = this.#requireBinding(envelope.type);
|
|
const schemaId = schemaIdForEnvelope(envelope, binding);
|
|
|
|
if (requestedSchemaIds && !answersTo(schemaId, binding, requestedSchemaIds)) {
|
|
continue;
|
|
}
|
|
|
|
if (requestedKeys && !requestedKeys.has(envelope.key)) {
|
|
continue;
|
|
}
|
|
|
|
documents.push(this.#createRawDocumentRecord(envelope));
|
|
}
|
|
|
|
return {
|
|
schemaVersion: "cultnet.snapshot_response_raw.v0",
|
|
messageId,
|
|
documents,
|
|
};
|
|
}
|
|
|
|
async applyDocumentPutMessage(
|
|
cache: CultCache,
|
|
message: CultNetDocumentPutMessage,
|
|
): Promise<unknown> {
|
|
const binding = this.#requireSchemaBinding(message.document.schemaId);
|
|
return cache.put(
|
|
binding.definition,
|
|
message.document.recordKey,
|
|
binding.definition.schema.parse(message.document.payload),
|
|
);
|
|
}
|
|
|
|
async applyDocumentDeleteMessage(
|
|
cache: CultCache,
|
|
message: CultNetDocumentDeleteMessage,
|
|
): Promise<boolean> {
|
|
const binding = this.#requireSchemaBinding(message.schemaId);
|
|
return cache.delete(binding.definition, message.recordKey);
|
|
}
|
|
|
|
async applyRawDocumentPutMessage(
|
|
cache: CultCache,
|
|
message: CultNetDocumentPutRawMessage,
|
|
): Promise<unknown> {
|
|
const { binding, envelope } = this.#rawPutEnvelope(message);
|
|
return cache.putEnvelope(binding.definition, envelope);
|
|
}
|
|
|
|
/**
|
|
* The snapshot response that would serve this raw put's document alone: the
|
|
* record `applyRawDocumentPutMessage` would store, as `createRawSnapshotResponse`
|
|
* would serve it. A server uses it to judge a put by the size it would be
|
|
* served at. Throws, as the put would, when no binding accepts the document.
|
|
*/
|
|
createRawSnapshotResponseForPut(
|
|
message: CultNetDocumentPutRawMessage,
|
|
messageId: string,
|
|
): CultNetSnapshotResponseRawMessage {
|
|
const { envelope } = this.#rawPutEnvelope(message);
|
|
return {
|
|
schemaVersion: "cultnet.snapshot_response_raw.v0",
|
|
messageId,
|
|
documents: [this.#createRawDocumentRecord(envelope)],
|
|
};
|
|
}
|
|
|
|
#rawPutEnvelope(message: CultNetDocumentPutRawMessage): {
|
|
binding: CultNetDocumentBinding;
|
|
envelope: CultCacheEnvelope;
|
|
} {
|
|
const binding = this.#requireSchemaBinding(message.document.schemaId);
|
|
return {
|
|
binding,
|
|
envelope: {
|
|
key: message.document.recordKey,
|
|
type: binding.definition.type,
|
|
schemaId: schemaIdForBinding(binding),
|
|
payload: documentPayloadFromBytes(new Uint8Array(documentPayloadBytes(message.document.payload))),
|
|
storedAt: message.document.storedAt,
|
|
},
|
|
};
|
|
}
|
|
|
|
async applySnapshotResponse(
|
|
cache: CultCache,
|
|
response: CultNetSnapshotResponseMessage,
|
|
): Promise<void> {
|
|
for (const document of response.documents) {
|
|
await this.applyDocumentPutMessage(cache, {
|
|
schemaVersion: "cultnet.document_put.v0",
|
|
messageId: response.messageId,
|
|
document,
|
|
});
|
|
}
|
|
}
|
|
|
|
async applyRawSnapshotResponse(
|
|
cache: CultCache,
|
|
response: CultNetSnapshotResponseRawMessage,
|
|
): Promise<void> {
|
|
for (const document of response.documents) {
|
|
await this.applyRawDocumentPutMessage(cache, {
|
|
schemaVersion: "cultnet.document_put_raw.v0",
|
|
messageId: response.messageId,
|
|
document,
|
|
});
|
|
}
|
|
}
|
|
|
|
#requireBinding(documentType: string): CultNetDocumentBinding {
|
|
const binding = this.get(documentType);
|
|
if (!binding) {
|
|
throw new Error(`No CultNet document binding is registered for "${documentType}".`);
|
|
}
|
|
|
|
return binding;
|
|
}
|
|
|
|
#requireSchemaBinding(schemaId: string): CultNetDocumentBinding {
|
|
const binding = this.getBySchemaId(schemaId);
|
|
if (!binding) {
|
|
throw new Error(`No CultNet document binding is registered for schema "${schemaId}".`);
|
|
}
|
|
|
|
return binding;
|
|
}
|
|
|
|
#createRawDocumentRecord(envelope: CultCacheEnvelope): CultNetRawDocumentRecord {
|
|
const binding = this.#requireBinding(envelope.type);
|
|
return {
|
|
schemaId: schemaIdForEnvelope(envelope, binding),
|
|
recordKey: envelope.key,
|
|
storedAt: envelope.storedAt,
|
|
payloadEncoding: "messagepack",
|
|
payload: documentPayloadFromBytes(new Uint8Array(documentPayloadBytes(envelope.payload))),
|
|
};
|
|
}
|
|
}
|
|
|
|
function schemaIdForBinding(binding: CultNetDocumentBinding): string {
|
|
return schemaIdentityOf(binding.definition).schemaId;
|
|
}
|
|
|
|
// A held record matches a snapshot filter when the filter names the id it carries or any id its binding answers to.
|
|
function answersTo(
|
|
schemaId: string,
|
|
binding: CultNetDocumentBinding,
|
|
requestedSchemaIds: Set<string>,
|
|
): boolean {
|
|
return requestedSchemaIds.has(schemaId)
|
|
|| schemaIdentityOf(binding.definition).compatibleSchemaIds.some(candidate => requestedSchemaIds.has(candidate));
|
|
}
|
|
|
|
function schemaIdForEnvelope(
|
|
envelope: CultCacheEnvelope,
|
|
binding: CultNetDocumentBinding,
|
|
): string {
|
|
return envelope.schemaId ?? schemaIdForBinding(binding);
|
|
}
|
|
|
|
function resolvePayloadSchemaVersion<TDefinition extends AnyCultCacheDocumentDefinition>(
|
|
binding: CultNetDocumentBinding<TDefinition>,
|
|
value: CultCacheDocumentValue<TDefinition>,
|
|
): string | undefined {
|
|
if (typeof binding.payloadSchemaVersion === "function") {
|
|
return binding.payloadSchemaVersion(value);
|
|
}
|
|
|
|
return binding.payloadSchemaVersion;
|
|
}
|