apache-iggy 0.10.0 → 0.10.1-edge.2

package/dist/client/client.operation.js

@@ -0,0 +1,428 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+import { HEADER_SIZE, REQUEST_OFFSET } from '../wire/vsr/header.js';
+import { responseError } from '../wire/error.utils.js';
+const INVALID_MESSAGE_LENGTH = 80;
+const TRANSIENT_NOT_ACCEPTED = 58;
+export const OPERATION_TIMEOUT_MS = 30_000;
+export class OperationUncertainError extends Error {
+    operationId;
+    constructor(operationId, cause) {
+        super('The operation outcome is unknown.', { cause });
+        this.operationId = operationId;
+        this.name = 'OperationUncertainError';
+    }
+}
+export class LaneBlockedError extends Error {
+    operationId;
+    constructor(operationId) {
+        super('A retained operation blocks this mutation lane.');
+        this.operationId = operationId;
+        this.name = 'LaneBlockedError';
+    }
+}
+/**
+ * The client has neither the operation nor a proved outcome for it, so the
+ * outcome can still be unknown. A session reset or an abandon came before a
+ * replay proved the outcome, or the proved outcome aged out.
+ */
+export class OperationNotRetainedError extends Error {
+    operationId;
+    constructor(operationId) {
+        super('The operation is not retained; its outcome may still be unknown.');
+        this.operationId = operationId;
+        this.name = 'OperationNotRetainedError';
+    }
+}
+export class VsrResponseTimeoutError extends Error {
+    constructor(timeout) {
+        super(`timed out after ${timeout} ms waiting for VSR response`);
+        this.name = 'VsrResponseTimeoutError';
+    }
+}
+/**
+ * Every replica link used its retry budget, or no endpoint accepted a dial.
+ * The client connects again on its own: each heartbeat restarts a link with a
+ * fresh budget, and the next call dials again.
+ */
+export class NotConnectedError extends Error {
+    constructor(cause) {
+        super('The client is not connected to any replica.', { cause });
+        this.name = 'NotConnectedError';
+    }
+}
+export const waitWithin = async (pending, deadline, signal) => {
+    void pending.catch(() => undefined);
+    signal?.throwIfAborted();
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new VsrResponseTimeoutError(0);
+    let timer;
+    let abort;
+    try {
+        return await Promise.race([pending, new Promise((_resolve, reject) => {
+                if (remaining <= 2_147_483_647)
+                    timer = setTimeout(() => reject(new VsrResponseTimeoutError(remaining)), remaining);
+                abort = () => reject(signal?.reason ?? new Error('operation aborted'));
+                signal?.addEventListener('abort', abort, { once: true });
+            })]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (abort)
+            signal?.removeEventListener('abort', abort);
+    }
+};
+export const pause = (milliseconds, signal, background = false) => {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener('abort', abort);
+        const timer = setTimeout(() => { cleanup(); resolve(); }, milliseconds);
+        if (background)
+            timer.unref();
+        const abort = () => { clearTimeout(timer); cleanup(); reject(signal?.reason); };
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+};
+export class ChangeSignal {
+    resolve;
+    promise = this.next();
+    next() {
+        return new Promise((resolve) => { this.resolve = resolve; });
+    }
+    pulse() {
+        const resolve = this.resolve;
+        this.promise = this.next();
+        resolve();
+    }
+}
+export class PermitPool {
+    capacity;
+    active = 0;
+    waiting = [];
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    async acquire(deadline, signal) {
+        signal.throwIfAborted();
+        if (this.active < this.capacity && this.waiting.length === 0) {
+            this.active += 1;
+            return () => this.release();
+        }
+        let grant;
+        const pending = new Promise((resolve) => { grant = resolve; });
+        const waiter = { grant, granted: false };
+        this.waiting.push(waiter);
+        try {
+            await waitWithin(pending, deadline, signal);
+            return () => this.release();
+        }
+        catch (error) {
+            if (waiter.granted)
+                this.release();
+            else
+                this.waiting.splice(this.waiting.indexOf(waiter), 1);
+            throw error;
+        }
+    }
+    release() {
+        const waiter = this.waiting.shift();
+        if (waiter) {
+            waiter.granted = true;
+            waiter.grant();
+        }
+        else
+            this.active -= 1;
+    }
+}
+/** Writer aliases pin physical bytes after logical completion or abandonment. */
+export class FrozenFrame {
+    bytes;
+    released;
+    references = 1;
+    ownerReleased = false;
+    constructor(bytes, released) {
+        this.bytes = bytes;
+        this.released = released;
+    }
+    get buffer() {
+        if (!this.bytes)
+            throw new Error('request frame was released');
+        return this.bytes;
+    }
+    retain() {
+        if (!this.bytes)
+            throw new Error('request frame was released');
+        this.references += 1;
+    }
+    release() {
+        this.references -= 1;
+        if (this.references === 0) {
+            this.bytes?.fill(0);
+            this.bytes = undefined;
+            this.released();
+        }
+    }
+    releaseOwner() {
+        if (!this.ownerReleased) {
+            this.ownerReleased = true;
+            this.release();
+        }
+    }
+}
+export class MutationLanes {
+    maxOperations;
+    maxBytes;
+    lanes = new Map();
+    operations = new Map();
+    /**
+     * The outcomes that replays proved, oldest first: the committed rejection,
+     * or `undefined` for a committed success. A reset keeps them, because
+     * operation ids never repeat within a client.
+     */
+    proved = new Map();
+    waiting = new Map();
+    capacityWaiting = new Set();
+    changed = new ChangeSignal();
+    count = 0;
+    bytes = 0;
+    constructor(maxOperations, maxBytes) {
+        this.maxOperations = maxOperations;
+        this.maxBytes = maxBytes;
+    }
+    async enter(lane, command, body, context, retainable, session, deadline, signal) {
+        const size = retainable ? HEADER_SIZE + body.length : 0;
+        if (!Number.isSafeInteger(size) || size > this.maxBytes)
+            throw responseError(command, INVALID_MESSAGE_LENGTH, 'request exceeds the mutation byte limit');
+        const waiting = { size, retainable, changed: new ChangeSignal() };
+        let queue = this.waiting.get(lane);
+        if (!queue) {
+            queue = {};
+            this.waiting.set(lane, queue);
+        }
+        waiting.previous = queue.tail;
+        if (queue.tail)
+            queue.tail.next = waiting;
+        else
+            queue.head = waiting;
+        queue.tail = waiting;
+        try {
+            for (;;) {
+                signal.throwIfAborted();
+                if (Date.now() >= deadline)
+                    throw responseError(command, TRANSIENT_NOT_ACCEPTED);
+                this.throwIfRetained(lane);
+                const head = !this.lanes.has(lane) && queue.head === waiting;
+                if (head &&
+                    (!retainable || this.count < this.maxOperations) && size <= this.maxBytes - this.bytes) {
+                    if (retainable)
+                        this.count += 1;
+                    this.bytes += size;
+                    let bytes;
+                    try {
+                        bytes = session.encode(command, body, context);
+                    }
+                    catch (error) {
+                        if (retainable)
+                            this.count -= 1;
+                        this.bytes -= size;
+                        throw error;
+                    }
+                    const operation = {
+                        lane, command, context, retainable,
+                        id: bytes.readBigUInt64LE(REQUEST_OFFSET.request),
+                        frame: this.freeze(bytes, size),
+                        lifetime: new AbortController(), resolving: false, retained: false, uncertain: false,
+                        holdsSlot: retainable
+                    };
+                    this.lanes.set(lane, operation);
+                    this.operations.set(operation.id, operation);
+                    return operation;
+                }
+                if (head)
+                    this.capacityWaiting.add(waiting);
+                await waitWithin(waiting.changed.promise, deadline, signal);
+            }
+        }
+        catch (error) {
+            if (!signal.aborted && error instanceof VsrResponseTimeoutError)
+                throw responseError(command, TRANSIENT_NOT_ACCEPTED);
+            throw error;
+        }
+        finally {
+            if (waiting.previous)
+                waiting.previous.next = waiting.next;
+            else
+                queue.head = waiting.next;
+            if (waiting.next)
+                waiting.next.previous = waiting.previous;
+            else
+                queue.tail = waiting.previous;
+            this.capacityWaiting.delete(waiting);
+            if (!queue.head)
+                this.waiting.delete(lane);
+            this.wakeLane(lane);
+            this.wakeWaiting();
+        }
+    }
+    async restart(operation, body, context, session, deadline, signal) {
+        operation.frame.releaseOwner();
+        const size = operation.retainable ? HEADER_SIZE + body.length : 0;
+        for (;;) {
+            signal.throwIfAborted();
+            if (!this.owns(operation))
+                throw new OperationNotRetainedError(operation.id);
+            if (Date.now() >= deadline)
+                throw new VsrResponseTimeoutError(0);
+            if (size <= this.maxBytes - this.bytes)
+                break;
+            await waitWithin(this.changed.promise, deadline, signal);
+        }
+        const bytes = session.encode(operation.command, body, context);
+        this.bytes += size;
+        this.operations.delete(operation.id);
+        operation.id = bytes.readBigUInt64LE(REQUEST_OFFSET.request);
+        operation.context = context;
+        operation.frame = this.freeze(bytes, size);
+        this.operations.set(operation.id, operation);
+    }
+    freeze(bytes, size) {
+        return new FrozenFrame(bytes, () => {
+            this.bytes -= size;
+            this.wakeWaiting();
+            this.changed.pulse();
+        });
+    }
+    throwIfRetained(lane) {
+        const operation = this.lanes.get(lane);
+        if (operation?.retained)
+            throw new LaneBlockedError(operation.id);
+    }
+    retained(id) {
+        const operation = this.operations.get(id);
+        if (!operation?.retained)
+            throw new OperationNotRetainedError(id);
+        return operation;
+    }
+    owns(operation) {
+        return this.operations.get(operation.id) === operation;
+    }
+    retain(operation) {
+        // A replay keeps the state it has, which an abandon can have dropped.
+        if (operation.retainable && this.owns(operation) && !operation.resolving) {
+            operation.retained = true;
+            for (let waiter = this.waiting.get(operation.lane)?.head; waiter; waiter = waiter.next)
+                waiter.changed.pulse();
+            this.changed.pulse();
+        }
+    }
+    /** Completes a call that proved its outcome. A replay keeps the outcome for a later resolve. */
+    prove(operation, rejection) {
+        if (operation.resolving) {
+            if (this.proved.size >= this.maxOperations)
+                this.proved.delete(this.proved.keys().next().value);
+            this.proved.set(operation.id, rejection);
+        }
+        this.complete(operation);
+    }
+    /** Returns or throws the outcome that a replay proved for `id`. */
+    provedOutcome(id) {
+        if (!this.proved.has(id))
+            throw new OperationNotRetainedError(id);
+        const rejection = this.proved.get(id);
+        if (rejection !== undefined)
+            throw rejection;
+    }
+    /**
+     * Drops the retained operation `id`, whose outcome stays unknown, and frees
+     * its slot. A running replay keeps the lane until it ends, so the lane stays
+     * FIFO.
+     */
+    abandon(id) {
+        const operation = this.retained(id);
+        operation.retained = false;
+        if (!operation.resolving) {
+            this.complete(operation);
+            return;
+        }
+        this.releaseSlot(operation);
+        this.wakeWaiting();
+    }
+    complete(operation) {
+        if (!this.owns(operation))
+            return;
+        this.operations.delete(operation.id);
+        this.lanes.delete(operation.lane);
+        this.releaseSlot(operation);
+        operation.lifetime.abort(new OperationNotRetainedError(operation.id));
+        operation.frame.releaseOwner();
+        this.wakeLane(operation.lane);
+        this.wakeWaiting();
+        this.changed.pulse();
+    }
+    /**
+     * Drops the retained operations and ends their replays, because no other
+     * session can replay their frames. A call keeps the lane it holds and starts
+     * again under the next session, so the calls in a lane keep their order.
+     */
+    reset() {
+        for (const operation of this.operations.values())
+            if (operation.retained || operation.resolving)
+                this.complete(operation);
+    }
+    releaseSlot(operation) {
+        if (!operation.holdsSlot)
+            return;
+        operation.holdsSlot = false;
+        this.count -= 1;
+    }
+    wakeLane(lane) {
+        const head = this.waiting.get(lane)?.head;
+        if (head && !this.lanes.has(lane))
+            this.capacityWaiting.add(head);
+    }
+    wakeWaiting() {
+        for (const waiter of this.capacityWaiting) {
+            if ((waiter.retainable && this.count >= this.maxOperations) ||
+                waiter.size > this.maxBytes - this.bytes)
+                continue;
+            waiter.changed.pulse();
+            return;
+        }
+    }
+    async acquireResolution(operation, deadline, signal) {
+        try {
+            while (operation.resolving) {
+                await waitWithin(this.changed.promise, deadline, signal);
+            }
+        }
+        catch (error) {
+            throw error instanceof VsrResponseTimeoutError ? new OperationUncertainError(operation.id, error) : error;
+        }
+        if (!this.owns(operation))
+            throw new OperationNotRetainedError(operation.id);
+        operation.resolving = true;
+        return () => {
+            operation.resolving = false;
+            // An abandon left the lane to this replay until now.
+            if (!operation.retained)
+                this.complete(operation);
+            this.changed.pulse();
+        };
+    }
+}
+//# sourceMappingURL=client.operation.js.map

package/dist/client/client.operation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.operation.test.d.ts.map