WIP (unverified): publishRudpDocumentOnce sendOnly + presence publisher send-only; tests written, cultmesh-ts receipt-client run hung
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
c89c4ee39a
commit
0caef4d564
5 changed files with 164 additions and 26 deletions
|
|
@ -11,6 +11,7 @@ All notable changes to `@gamecult/cultmesh-ts` are recorded here, following
|
|||
|
||||
### Breaking
|
||||
|
||||
- `publishRudpDocumentOnce` no longer treats a window with no refusal as published: a put nothing settled in its result window (500 ms, or 5000 ms against a receipt-capable server) rejects `CultMeshRudpWriteUnconfirmedError`, and a legacy server's echo of the put's id is not admission. It now resolves `"admitted"` (only on a `write_admitted`) or `"sent"`. **Migration:** a caller whose server cannot answer a write yet (for example Odin, until it is receipt-capable) passes `sendOnly: true` per call and treats `"sent"` as "sent", never as admitted. Receipts stay opt-in (`writeReceipts: true`); neither mode is the default.
|
||||
- The package is renamed `cultmesh-ts` to `@gamecult/cultmesh-ts` (the repo already scopes `@gamecult/cultcache-ts`), so the unscoped name cannot be claimed by someone else. Import from `@gamecult/cultmesh-ts` and its subpaths; the API is unchanged. Depends on `@gamecult/cultnet-ts`.
|
||||
- `asSchemaAlias` is removed from `CultMeshDocumentHandle`, `CultMeshCollectionHandle` and their bound forms. Read the handle by the schema you mean.
|
||||
- `CultMeshDocumentCatalog` (`document`, `tryDocument`, `latest`, `replace`, `submitPrediction`, `authoritativeWriter`, `predictionWriter`, `watch`) and `CultMeshCollectionCatalog` (`collection`, `tryCollection`, `latest`, `watchChanges`) take `<TDocument = never, TSchema>` and yield `CultMeshCatalogValue<TDocument, TSchema>`: an explicit type argument wins, a CultCache document definition names its own value type, and a bare schema descriptor yields `unknown`. A value type is no longer inferred from a value or an expected result. The `parse` option is removed from these calls, and a lookup by type answers with that type's handle or none, not an alias of a compatible schema.
|
||||
|
|
|
|||
|
|
@ -4239,6 +4239,14 @@ export interface CultMeshRudpDocumentPublishOptions extends CultMeshRudpPeerOpti
|
|||
writeReceipts?: boolean;
|
||||
/** With `writeReceipts`, how long to wait for the server's hello before treating it as legacy. Default 500 ms. */
|
||||
helloWaitMs?: number;
|
||||
/**
|
||||
* Send the put and report only that it was sent: no hello, no wait for a result frame. Resolves `"sent"` once the
|
||||
* transport has acknowledged the put (`flushTimeoutMs`), rejects `CultMeshRudpWriteUnconfirmedError`
|
||||
* (`local_send_failed`) if it cannot be sent, and never resolves `"admitted"`: whether the server applied or
|
||||
* refused it is unknown. For callers whose server cannot answer a write yet. Opt-in per call; not combinable with
|
||||
* `writeReceipts`.
|
||||
*/
|
||||
sendOnly?: boolean;
|
||||
messageId?: string;
|
||||
sourceRuntimeId?: string;
|
||||
sourceAgentId?: string;
|
||||
|
|
@ -6208,13 +6216,35 @@ export class CultMesh {
|
|||
recordKey: string,
|
||||
value: CultCacheDocumentValue<TDefinition>,
|
||||
options: CultMeshRudpDocumentPublishOptions = {},
|
||||
): Promise<void> {
|
||||
): Promise<"admitted" | "sent"> {
|
||||
requireNonEmpty(runtimeId, "runtimeId");
|
||||
requireNonEmpty(recordKey, "recordKey");
|
||||
if (options.sendOnly && options.writeReceipts) throw new TypeError("sendOnly and writeReceipts cannot be combined.");
|
||||
const registry = new CultNetDocumentRegistry([binding]);
|
||||
const messageId = options.messageId ?? `${runtimeId}:${binding.definition.type}:${recordKey}`;
|
||||
const putMessage = () => registry.createRawDocumentPutMessage(
|
||||
binding,
|
||||
messageId,
|
||||
recordKey,
|
||||
value,
|
||||
{
|
||||
sourceRuntimeId: options.sourceRuntimeId ?? runtimeId,
|
||||
sourceAgentId: options.sourceAgentId,
|
||||
sourceRole: options.sourceRole,
|
||||
tags: options.tags,
|
||||
},
|
||||
);
|
||||
const peer = await CultMesh.createRudpPeer(runtimeId, connectionId, endpoint, options);
|
||||
try {
|
||||
if (options.sendOnly) {
|
||||
try {
|
||||
peer.send(putMessage());
|
||||
await peer.flush(options.flushTimeoutMs ?? 30_000);
|
||||
} catch {
|
||||
throw new CultMeshRudpWriteUnconfirmedError(messageId, "local_send_failed");
|
||||
}
|
||||
return "sent";
|
||||
}
|
||||
// A transport ack is not admission: the put completes on its result frame, and the WriteTracker alone decides
|
||||
// how it settles (write-receipt.md, "Client rules"). This function only maps the settlement to resolve/throw.
|
||||
let receiptCapable = false;
|
||||
|
|
@ -6248,18 +6278,7 @@ export class CultMesh {
|
|||
tracker = writeTracker;
|
||||
writeTracker.send(messageId, Date.now());
|
||||
try {
|
||||
peer.send(registry.createRawDocumentPutMessage(
|
||||
binding,
|
||||
messageId,
|
||||
recordKey,
|
||||
value,
|
||||
{
|
||||
sourceRuntimeId: options.sourceRuntimeId ?? runtimeId,
|
||||
sourceAgentId: options.sourceAgentId,
|
||||
sourceRole: options.sourceRole,
|
||||
tags: options.tags,
|
||||
},
|
||||
));
|
||||
peer.send(putMessage());
|
||||
// The flush may not outlast the result window: a send nobody acknowledged by then is a local send failure.
|
||||
const windowRemaining = writeTracker.nextDeadlineMs(Date.now()) ?? 0;
|
||||
await peer.flush(Math.min(options.flushTimeoutMs ?? 30_000, Math.max(windowRemaining, 1)));
|
||||
|
|
@ -6277,6 +6296,7 @@ export class CultMesh {
|
|||
}
|
||||
if (settlement.outcome === "refused") throw new CultMeshRudpWriteRefusedError(settlement.response);
|
||||
if (settlement.outcome === "unconfirmed") throw new CultMeshRudpWriteUnconfirmedError(messageId, settlement.reason);
|
||||
return "admitted";
|
||||
} finally {
|
||||
peer.close();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -175,6 +175,37 @@ test("a server that does not advertise receipts and echoes the put's id back has
|
|||
} finally { server.close(); }
|
||||
});
|
||||
|
||||
test("a silent server never yields admitted, in either mode: the default is unconfirmed, sendOnly is the distinct outcome sent", async () => {
|
||||
const server = await fakeServer(nextConnection, { advertise: false, answer: "silence" });
|
||||
try {
|
||||
await assert.rejects(publish(server, { resultWindowMs: 200 }), CultMeshRudpWriteUnconfirmedError);
|
||||
const outcome = await publish(server, { sendOnly: true });
|
||||
assert.equal(outcome, "sent");
|
||||
assert.notEqual(outcome, "admitted");
|
||||
assert.deepEqual(server.seen, ["cultnet.document_put_raw.v0", "cultnet.document_put_raw.v0"], "sendOnly sends no hello");
|
||||
} finally { server.close(); }
|
||||
});
|
||||
|
||||
test("only a write_admitted resolves admitted, and sendOnly does not wait for or act on an answer", async () => {
|
||||
const admitting = await fakeServer(nextConnection, { advertise: true, answer: "admit" });
|
||||
try {
|
||||
assert.equal(await publish(admitting, { writeReceipts: true }), "admitted");
|
||||
} finally { admitting.close(); }
|
||||
const refusing = await fakeServer(nextConnection, { advertise: true, answer: "refuse", delayMs: 1 });
|
||||
try {
|
||||
assert.equal(await publish(refusing, { sendOnly: true }), "sent", "a refusal is not awaited: sendOnly says only that the put was sent");
|
||||
} finally { refusing.close(); }
|
||||
});
|
||||
|
||||
test("sendOnly fails local_send_failed when the send is never acknowledged, and cannot be combined with writeReceipts", async () => {
|
||||
const server = await fakeServer(nextConnection, { advertise: true, answer: "admit", ack: false });
|
||||
try {
|
||||
await assert.rejects(publish(server, { sendOnly: true, flushTimeoutMs: 300 }), (error: unknown) =>
|
||||
error instanceof CultMeshRudpWriteUnconfirmedError && error.reason === "local_send_failed");
|
||||
await assert.rejects(publish(server, { sendOnly: true, writeReceipts: true }), TypeError);
|
||||
} finally { server.close(); }
|
||||
});
|
||||
|
||||
test("without writeReceipts no hello is sent and the receipt frames are never asked for", async () => {
|
||||
const server = await fakeServer(nextConnection, { advertise: true, answer: "silence" });
|
||||
try {
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ export function createIdunnRuntimePresencePublisher(
|
|||
const publish = async (detail: string) => {
|
||||
const signed = signer.sign(detail);
|
||||
messageSequence += 1;
|
||||
await publishDocument(endpoint, connectionId, {
|
||||
await sendPresenceDocument(endpoint, connectionId, {
|
||||
schemaVersion: "cultnet.document_put_raw.v0",
|
||||
messageId: `runtime-presence:${signer.authority.expected.target}:${signer.runtimeInstanceId}:${messageSequence}`,
|
||||
document: signed.document,
|
||||
|
|
@ -86,11 +86,19 @@ export function createIdunnRuntimePresencePublisher(
|
|||
};
|
||||
}
|
||||
|
||||
async function publishDocument(
|
||||
/**
|
||||
* Sends one presence put and says only that it was sent (write-receipt.md: the explicit send-only mode). Odin does not
|
||||
* answer a write with a receipt yet, so no frame, whatever id it carries, is admission; this never claims it. It returns
|
||||
* once the transport has acknowledged the put, rejects `IdunnPresenceRefusedError` if a refusal arrives by then, and
|
||||
* rejects if the put is never acknowledged.
|
||||
*
|
||||
* @internal exported for tests
|
||||
*/
|
||||
export async function sendPresenceDocument(
|
||||
endpoint: { host: string; port: number },
|
||||
connectionId: number,
|
||||
message: Record<string, unknown>,
|
||||
): Promise<void> {
|
||||
): Promise<"sent"> {
|
||||
const socket = dgram.createSocket(endpoint.host.includes(":") ? "udp6" : "udp4");
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
socket.once("error", reject);
|
||||
|
|
@ -107,26 +115,24 @@ async function publishDocument(
|
|||
const wirePayload = encode(encodeCultNetMessageForWire(message as never, "cultnet.schema.v0"));
|
||||
const packets = session.sendMany("schema", wirePayload, { reliable: true, ordered: true, nowMs: Date.now() });
|
||||
for (const packet of packets) await sendPacket(socket, endpoint, packet);
|
||||
// The transport ack is not admission: the put completes on Odin's result frame. A refusal rejects whether
|
||||
// it arrives before the ack, after it, or inside the result window; a success reply ends the wait early.
|
||||
let succeeded = false;
|
||||
// The transport ack is delivery, not admission. A refusal that arrives by then rejects; no other frame means anything.
|
||||
const onFrame = (frame: { channelId: string; payload: Uint8Array }) => {
|
||||
if (frame.channelId !== "schema") return;
|
||||
const response = parseCultNetMessage(decode(frame.payload));
|
||||
if (response.schemaVersion === "cultnet.error.v0") throw new IdunnPresenceRefusedError(response);
|
||||
succeeded = true;
|
||||
// An error.v1 refuses this put only when it names it (or names nothing).
|
||||
if (response.schemaVersion === "cultnet.error.v1" && (response.messageId === null || response.messageId === message.messageId)) {
|
||||
throw new IdunnPresenceRefusedError(response);
|
||||
}
|
||||
};
|
||||
await receiveUntil(receiver, session, endpoint, () => session.outstandingReliablePacketCount === 0, 2000, onFrame);
|
||||
if (!succeeded) await receiveUntil(receiver, session, endpoint, () => succeeded, RESULT_WINDOW_MS, onFrame, true);
|
||||
return "sent";
|
||||
} finally {
|
||||
receiver.close();
|
||||
socket.close();
|
||||
}
|
||||
}
|
||||
|
||||
/** How long after the transport ack Odin's refusal may still arrive; a success reply ends the wait early. */
|
||||
const RESULT_WINDOW_MS = 500;
|
||||
|
||||
/** Odin refused the presence put: the typed `cultnet.error.v0` it answered with. */
|
||||
export class IdunnPresenceRefusedError extends Error {
|
||||
readonly code: string | undefined;
|
||||
|
|
@ -200,7 +206,6 @@ async function receiveUntil(
|
|||
predicate: (packet: CultNetRudpPacket) => boolean,
|
||||
timeoutMs: number,
|
||||
onDelivered?: (frame: { channelId: string; payload: Uint8Array; sequence: number }) => void,
|
||||
returnOnTimeout = false,
|
||||
): Promise<void> {
|
||||
const deadline = Date.now() + timeoutMs;
|
||||
while (Date.now() < deadline) {
|
||||
|
|
@ -215,7 +220,6 @@ async function receiveUntil(
|
|||
}
|
||||
for (const packet of session.dueResends(Date.now())) await sendPacket(receiver.socket, endpoint, packet);
|
||||
}
|
||||
if (returnOnTimeout) return;
|
||||
throw new Error(`Timed out waiting for CultNet RUDP response after ${timeoutMs} ms.`);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,82 @@
|
|||
// The presence publisher is send-only (write-receipt.md): Odin answers no write with a receipt yet, so no frame, whatever
|
||||
// id it carries, is admission. Each test serves it a fake Odin that acknowledges the put and answers as scripted.
|
||||
import assert from "node:assert/strict";
|
||||
import { createSocket, type Socket } from "node:dgram";
|
||||
import test from "node:test";
|
||||
import { encode, decode } from "@msgpack/msgpack";
|
||||
|
||||
import { encodeCultNetMessageForWire, type CultNetMessage } from "../src/contracts";
|
||||
import { IdunnPresenceRefusedError, sendPresenceDocument } from "../src/idunn-odin-presence-publisher";
|
||||
import { CultNetRudpSession, decodeRudpPacket, encodeRudpPacket } from "../src/rudp";
|
||||
|
||||
interface Script {
|
||||
answer: "silence" | "echo" | "admitted" | "refuse-v0" | "refuse-v1-other";
|
||||
/** Acknowledge the put? Default true. */
|
||||
ack?: boolean;
|
||||
}
|
||||
|
||||
async function fakeOdin(connectionId: number, script: Script) {
|
||||
const socket: Socket = createSocket("udp4");
|
||||
await new Promise<void>((resolve) => socket.bind(0, "127.0.0.1", resolve));
|
||||
const session = new CultNetRudpSession({ connectionId, resendDelayMs: 50 });
|
||||
const send = (packet: Parameters<typeof encodeRudpPacket>[0], port: number, address: string) => {
|
||||
try { socket.send(encodeRudpPacket(packet), port, address); } catch { /* closed */ }
|
||||
};
|
||||
const say = (message: CultNetMessage, port: number, address: string) => {
|
||||
const packets = session.sendMany("schema", encode(encodeCultNetMessageForWire(message, "cultnet.schema.v0")), { reliable: true, ordered: true, nowMs: Date.now() });
|
||||
packets.forEach((p) => send(p, port, address));
|
||||
};
|
||||
socket.on("message", (wire, remote) => {
|
||||
const packet = decodeRudpPacket(wire);
|
||||
const now = Date.now();
|
||||
if (packet.packetType === "connect") {
|
||||
send(session.acceptConnect(packet, now), remote.port, remote.address);
|
||||
return;
|
||||
}
|
||||
const result = session.receive(packet, now);
|
||||
if (result.reply) send(result.reply, remote.port, remote.address);
|
||||
for (const frame of result.delivered) {
|
||||
if (frame.channelId !== "schema") continue;
|
||||
const put = decode(frame.payload) as { messageId: string; document: unknown };
|
||||
if (script.answer === "echo") say({ schemaVersion: "cultnet.document_put_raw.v0", messageId: put.messageId, document: put.document } as unknown as CultNetMessage, remote.port, remote.address);
|
||||
else if (script.answer === "admitted") say({ schemaVersion: "cultnet.write_admitted.v0", messageId: put.messageId, operation: "put", schemaId: "s", recordKey: "k" }, remote.port, remote.address);
|
||||
else if (script.answer === "refuse-v0") say({ schemaVersion: "cultnet.error.v0", error: "no", routingHint: null, code: "write_not_authorized", details: null }, remote.port, remote.address);
|
||||
else if (script.answer === "refuse-v1-other") say({ schemaVersion: "cultnet.error.v1", error: "no", routingHint: null, code: "write_not_authorized", details: null, messageId: "someone-else" }, remote.port, remote.address);
|
||||
}
|
||||
if (packet.reliable && script.ack !== false) send(session.createAckForReceived(packet.sequence), remote.port, remote.address);
|
||||
});
|
||||
return { port: socket.address().port, close: () => socket.close() };
|
||||
}
|
||||
|
||||
let nextConnection = 0x0d1d1000;
|
||||
const put = (id: string) => ({ schemaVersion: "cultnet.document_put_raw.v0", messageId: id, document: { schemaId: "s", recordKey: "k", storedAt: "t", payloadEncoding: "messagepack", payload: new Uint8Array([1]) } });
|
||||
const sendTo = (server: { port: number }, id: string, connectionId: number) =>
|
||||
sendPresenceDocument({ host: "127.0.0.1", port: server.port }, connectionId, put(id));
|
||||
|
||||
for (const answer of ["silence", "echo", "admitted", "refuse-v1-other"] as const) {
|
||||
test(`a ${answer} Odin yields sent, never admitted: no frame carrying the put's id is success`, async () => {
|
||||
const connectionId = nextConnection++;
|
||||
const server = await fakeOdin(connectionId, { answer });
|
||||
try {
|
||||
const outcome = await sendTo(server, "presence-1", connectionId);
|
||||
assert.equal(outcome, "sent");
|
||||
assert.notEqual(outcome as string, "admitted");
|
||||
} finally { server.close(); }
|
||||
});
|
||||
}
|
||||
|
||||
test("a refusal that arrives by the transport ack rejects the put", async () => {
|
||||
const connectionId = nextConnection++;
|
||||
const server = await fakeOdin(connectionId, { answer: "refuse-v0" });
|
||||
try {
|
||||
await assert.rejects(sendTo(server, "presence-1", connectionId), IdunnPresenceRefusedError);
|
||||
} finally { server.close(); }
|
||||
});
|
||||
|
||||
test("a put the transport never acknowledges is an error, not sent", async () => {
|
||||
const connectionId = nextConnection++;
|
||||
const server = await fakeOdin(connectionId, { answer: "silence", ack: false });
|
||||
try {
|
||||
await assert.rejects(sendTo(server, "presence-1", connectionId), /Timed out/);
|
||||
} finally { server.close(); }
|
||||
});
|
||||
Loading…
Reference in a new issue