@sealant/api-contracts-next 0.40.0-next.760 → 0.40.0-next.763

package/dist/core-api/workspace-forward.d.ts

@@ -4,6 +4,14 @@
  * refused upgrade, so v2 accepts the upgrade first and answers with one text frame: `ready`, after
  * which binary frames carry payload both ways, or `refused`, after which the server closes with
  * {@link FORWARD_REFUSED_CLOSE_CODE}. A request without an upgrade gets 426 and is never dialled.
+ *
+ * After `ready`, each direction is bounded by {@link FORWARD_V2_WINDOW}. A receiver sends
+ * `progress` with the cumulative bytes and frames it has consumed; a sender keeps what it has sent
+ * within the last `progress` plus the window, and sends nothing before the first `progress`
+ * (`{0,0}`), which opens the receiver's window. A receiver resets a sender that goes past it.
+ * `fin` ends one direction with the totals sent; `reset` ends both at once. Core sends a `progress`
+ * naming exactly what reached the workspace before its `fin`, so a client can tell whether
+ * everything it wrote arrived. {@link ForwardFlow} keeps this ledger for either side.
  */
 import { Schema } from "effect";
 export declare const FORWARD_V2_SUBPROTOCOL = "sealant.forward.v2";
@@ -35,16 +43,26 @@ export declare const FORWARD_REFUSAL_STATUS: {
     readonly "binding-unverifiable": 409;
     readonly "binding-unsupported": 409;
 };
-export declare const forwardBindingSchema: Schema.Struct<{
+/**
+ * What a forward reaches: whatever holds the port (`port`), or only a process of the session that
+ * `session` names (`session`), as the workspace runtime verified when it connected.
+ */
+export declare const forwardBindingSchema: Schema.Union<readonly [Schema.Struct<{
     readonly kind: Schema.Literal<"port">;
-}>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"session">;
+    readonly session: Schema.String;
+}>]>;
 export type ForwardBinding = typeof forwardBindingSchema.Type;
 export declare const forwardReadyFrameSchema: Schema.Struct<{
     readonly t: Schema.Literal<"ready">;
     readonly version: Schema.Literal<2>;
-    readonly binding: Schema.Struct<{
+    readonly binding: Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"port">;
-    }>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"session">;
+        readonly session: Schema.String;
+    }>]>;
 }>;
 export type ForwardReadyFrame = typeof forwardReadyFrameSchema.Type;
 /**
@@ -68,9 +86,12 @@ export declare const forwardRefusedFrame: (reason: "binding-unsupported" | "bind
 export declare const forwardOpenFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly t: Schema.Literal<"ready">;
     readonly version: Schema.Literal<2>;
-    readonly binding: Schema.Struct<{
+    readonly binding: Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"port">;
-    }>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"session">;
+        readonly session: Schema.String;
+    }>]>;
 }>, Schema.Struct<{
     readonly t: Schema.Literal<"refused">;
     readonly reason: Schema.String;
@@ -78,3 +99,87 @@ export declare const forwardOpenFrameSchema: Schema.Union<readonly [Schema.Struc
     readonly status: Schema.Int;
 }>]>;
 export type ForwardOpenFrame = typeof forwardOpenFrameSchema.Type;
+/** What each direction of a v2 forward may have in flight beyond what its receiver consumed. */
+export declare const FORWARD_V2_WINDOW: {
+    readonly bytes: number;
+    readonly frames: 32;
+};
+export declare const forwardProgressFrameSchema: Schema.Struct<{
+    readonly t: Schema.Literal<"progress">;
+    readonly bytes: Schema.String;
+    readonly frames: Schema.String;
+}>;
+export type ForwardProgressFrame = typeof forwardProgressFrameSchema.Type;
+export declare const forwardFinFrameSchema: Schema.Struct<{
+    readonly t: Schema.Literal<"fin">;
+    readonly bytes: Schema.String;
+    readonly frames: Schema.String;
+}>;
+export type ForwardFinFrame = typeof forwardFinFrameSchema.Type;
+export declare const forwardResetReasonSchema: Schema.Literals<readonly ["window-exceeded", "protocol-violation", "aborted", "target-error", "runtime-lost", "owner-exited"]>;
+export type ForwardResetReason = typeof forwardResetReasonSchema.Type;
+/** Decoded with any `reason`, so a client keeps a reset from a Core newer than itself. */
+export declare const forwardResetFrameSchema: Schema.Struct<{
+    readonly t: Schema.Literal<"reset">;
+    readonly reason: Schema.String;
+}>;
+export type ForwardResetFrame = typeof forwardResetFrameSchema.Type;
+/** The text frames either side sends after `ready`. */
+export declare const forwardFlowFrameSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly t: Schema.Literal<"progress">;
+    readonly bytes: Schema.String;
+    readonly frames: Schema.String;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"fin">;
+    readonly bytes: Schema.String;
+    readonly frames: Schema.String;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"reset">;
+    readonly reason: Schema.String;
+}>]>;
+export type ForwardFlowFrame = typeof forwardFlowFrameSchema.Type;
+/** What one frame from the peer meant, once the forward is open. */
+export type ForwardInbound = {
+    readonly kind: "data";
+    readonly data: Uint8Array;
+} | {
+    readonly kind: "progress";
+} | {
+    readonly kind: "fin";
+} | {
+    readonly kind: "reset";
+    readonly reason: string;
+} | {
+    readonly kind: "violation";
+    readonly reason: "window-exceeded" | "protocol-violation";
+};
+/** A chunk as the binary frames it is sent in. */
+export declare function forwardFrames(chunk: Uint8Array): Generator<Uint8Array>;
+/**
+ * Both directions of an open v2 forward as one side sees them, with no I/O: what it sent against
+ * what its peer consumed, and what it received and consumed against what it granted. Core and the
+ * SDK each drive one from their socket.
+ *
+ * A grant is made when its `progress` is sent, so a side that holds a `progress` back while its
+ * socket is backed up also holds back its peer, and the next `progress` it sends names the latest
+ * count: acknowledgements never queue.
+ */
+export declare class ForwardFlow {
+    #private;
+    /** The first `progress`, which lets the peer start sending. */
+    open(): ForwardProgressFrame;
+    receive(frame: string | Uint8Array): ForwardInbound;
+    /** Whether one frame of `bytes` fits in what the peer has granted. */
+    canSend(bytes: number): boolean;
+    sent(bytes: number): void;
+    /** Whether the peer has said it consumed everything this side sent. */
+    get delivered(): boolean;
+    fin(): ForwardFinFrame;
+    consumed(bytes: number): void;
+    /** Whether what was consumed since the last `progress` reaches half the window. */
+    get progressDue(): boolean;
+    /** The `progress` to send now, when one is due. Taking it makes the grant. */
+    takeProgress(): ForwardProgressFrame | undefined;
+    /** A `progress` naming exactly what was consumed, unless the last one already did. */
+    takeFinalProgress(): ForwardProgressFrame | undefined;
+}

package/dist/core-api/workspace-forward.js

@@ -4,8 +4,16 @@
  * refused upgrade, so v2 accepts the upgrade first and answers with one text frame: `ready`, after
  * which binary frames carry payload both ways, or `refused`, after which the server closes with
  * {@link FORWARD_REFUSED_CLOSE_CODE}. A request without an upgrade gets 426 and is never dialled.
+ *
+ * After `ready`, each direction is bounded by {@link FORWARD_V2_WINDOW}. A receiver sends
+ * `progress` with the cumulative bytes and frames it has consumed; a sender keeps what it has sent
+ * within the last `progress` plus the window, and sends nothing before the first `progress`
+ * (`{0,0}`), which opens the receiver's window. A receiver resets a sender that goes past it.
+ * `fin` ends one direction with the totals sent; `reset` ends both at once. Core sends a `progress`
+ * naming exactly what reached the workspace before its `fin`, so a client can tell whether
+ * everything it wrote arrived. {@link ForwardFlow} keeps this ledger for either side.
  */
-import { Schema } from "effect";
+import { Option, Schema } from "effect";
 export const FORWARD_V2_SUBPROTOCOL = "sealant.forward.v2";
 /** The largest binary frame either side may send. */
 export const FORWARD_V2_MAX_FRAME_BYTES = 64 * 1024;
@@ -54,7 +62,14 @@ export const FORWARD_REFUSAL_STATUS = {
     "binding-unverifiable": 409,
     "binding-unsupported": 409,
 };
-export const forwardBindingSchema = Schema.Struct({ kind: Schema.Literal("port") });
+/**
+ * What a forward reaches: whatever holds the port (`port`), or only a process of the session that
+ * `session` names (`session`), as the workspace runtime verified when it connected.
+ */
+export const forwardBindingSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("port") }),
+    Schema.Struct({ kind: Schema.Literal("session"), session: Schema.String }),
+]);
 export const forwardReadyFrameSchema = Schema.Struct({
     t: Schema.Literal("ready"),
     version: Schema.Literal(2),
@@ -81,3 +96,160 @@ export const forwardOpenFrameSchema = Schema.Union([
     forwardReadyFrameSchema,
     forwardRefusedFrameSchema,
 ]);
+/** What each direction of a v2 forward may have in flight beyond what its receiver consumed. */
+export const FORWARD_V2_WINDOW = { bytes: 256 * 1024, frames: 32 };
+const counterSchema = Schema.String.check(Schema.isPattern(/^(?:0|[1-9][0-9]{0,14})$/));
+export const forwardProgressFrameSchema = Schema.Struct({
+    t: Schema.Literal("progress"),
+    bytes: counterSchema,
+    frames: counterSchema,
+});
+export const forwardFinFrameSchema = Schema.Struct({
+    t: Schema.Literal("fin"),
+    bytes: counterSchema,
+    frames: counterSchema,
+});
+export const forwardResetReasonSchema = Schema.Literals([
+    "window-exceeded",
+    "protocol-violation",
+    "aborted",
+    "target-error",
+    "runtime-lost",
+    "owner-exited",
+]);
+/** Decoded with any `reason`, so a client keeps a reset from a Core newer than itself. */
+export const forwardResetFrameSchema = Schema.Struct({
+    t: Schema.Literal("reset"),
+    reason: Schema.String,
+});
+/** The text frames either side sends after `ready`. */
+export const forwardFlowFrameSchema = Schema.Union([
+    forwardProgressFrameSchema,
+    forwardFinFrameSchema,
+    forwardResetFrameSchema,
+]);
+const NOTHING = { bytes: 0, frames: 0 };
+const plusFrame = (count, bytes) => ({
+    bytes: count.bytes + bytes,
+    frames: count.frames + 1,
+});
+const countOf = (frame) => ({
+    bytes: Number(frame.bytes),
+    frames: Number(frame.frames),
+});
+const sameCount = (a, b) => a.bytes === b.bytes && a.frames === b.frames;
+const withinWindow = (count, granted) => count.bytes <= granted.bytes + FORWARD_V2_WINDOW.bytes &&
+    count.frames <= granted.frames + FORWARD_V2_WINDOW.frames;
+const counted = (t, count) => ({
+    t,
+    bytes: String(count.bytes),
+    frames: String(count.frames),
+});
+const decodeFlowFrame = Schema.decodeUnknownOption(Schema.fromJsonString(forwardFlowFrameSchema));
+const violation = (reason) => ({
+    kind: "violation",
+    reason,
+});
+/** A chunk as the binary frames it is sent in. */
+export function* forwardFrames(chunk) {
+    for (let offset = 0; offset < chunk.byteLength; offset += FORWARD_V2_MAX_FRAME_BYTES) {
+        yield chunk.subarray(offset, offset + FORWARD_V2_MAX_FRAME_BYTES);
+    }
+}
+/**
+ * Both directions of an open v2 forward as one side sees them, with no I/O: what it sent against
+ * what its peer consumed, and what it received and consumed against what it granted. Core and the
+ * SDK each drive one from their socket.
+ *
+ * A grant is made when its `progress` is sent, so a side that holds a `progress` back while its
+ * socket is backed up also holds back its peer, and the next `progress` it sends names the latest
+ * count: acknowledgements never queue.
+ */
+export class ForwardFlow {
+    #sent = NOTHING;
+    #peerConsumed;
+    #received = NOTHING;
+    #consumed = NOTHING;
+    #granted;
+    #finReceived = false;
+    /** The first `progress`, which lets the peer start sending. */
+    open() {
+        this.#granted = this.#consumed;
+        return counted("progress", this.#consumed);
+    }
+    receive(frame) {
+        if (typeof frame !== "string") {
+            if (this.#finReceived)
+                return violation("protocol-violation");
+            this.#received = plusFrame(this.#received, frame.byteLength);
+            const granted = this.#granted;
+            return granted !== undefined && withinWindow(this.#received, granted)
+                ? { kind: "data", data: frame }
+                : violation("window-exceeded");
+        }
+        const decoded = decodeFlowFrame(frame);
+        if (Option.isNone(decoded))
+            return violation("protocol-violation");
+        switch (decoded.value.t) {
+            case "progress":
+                return this.#acceptPeerProgress(countOf(decoded.value))
+                    ? { kind: "progress" }
+                    : violation("protocol-violation");
+            case "fin":
+                if (this.#finReceived || !sameCount(countOf(decoded.value), this.#received)) {
+                    return violation("protocol-violation");
+                }
+                this.#finReceived = true;
+                return { kind: "fin" };
+            case "reset":
+                return { kind: "reset", reason: decoded.value.reason };
+        }
+    }
+    #acceptPeerProgress(consumed) {
+        const previous = this.#peerConsumed ?? NOTHING;
+        if (consumed.bytes > this.#sent.bytes ||
+            consumed.frames > this.#sent.frames ||
+            consumed.bytes < previous.bytes ||
+            consumed.frames < previous.frames) {
+            return false;
+        }
+        this.#peerConsumed = consumed;
+        return true;
+    }
+    /** Whether one frame of `bytes` fits in what the peer has granted. */
+    canSend(bytes) {
+        const consumed = this.#peerConsumed;
+        return consumed !== undefined && withinWindow(plusFrame(this.#sent, bytes), consumed);
+    }
+    sent(bytes) {
+        this.#sent = plusFrame(this.#sent, bytes);
+    }
+    /** Whether the peer has said it consumed everything this side sent. */
+    get delivered() {
+        return this.#peerConsumed !== undefined && sameCount(this.#peerConsumed, this.#sent);
+    }
+    fin() {
+        return counted("fin", this.#sent);
+    }
+    consumed(bytes) {
+        this.#consumed = plusFrame(this.#consumed, bytes);
+    }
+    /** Whether what was consumed since the last `progress` reaches half the window. */
+    get progressDue() {
+        const granted = this.#granted ?? NOTHING;
+        return (this.#consumed.bytes - granted.bytes >= FORWARD_V2_WINDOW.bytes / 2 ||
+            this.#consumed.frames - granted.frames >= FORWARD_V2_WINDOW.frames / 2);
+    }
+    /** The `progress` to send now, when one is due. Taking it makes the grant. */
+    takeProgress() {
+        if (!this.progressDue)
+            return undefined;
+        return this.open();
+    }
+    /** A `progress` naming exactly what was consumed, unless the last one already did. */
+    takeFinalProgress() {
+        if (this.#granted !== undefined && sameCount(this.#granted, this.#consumed))
+            return undefined;
+        return this.open();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.40.0-next.760",
+  "version": "0.40.0-next.763",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "eb43ab8076dbdd584f026d068c478078a294d570",
+  "gitHead": "c741e10743b2c553b526f93565c256fe8fa4bd8b",
   "publishConfig": {
     "access": "public"
   }