@mfxhub/sdk 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,25 @@ Every release of `@mfxhub/sdk`, newest first. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.2.3
+
+### Added
+
+- Every HTTP attempt is timed. `new MfxClient(..., { onCall })` is told each one as a `CallTiming`
+  (`what`, `status`, `ms`; `status` is `null` when no answer came), and when the environment
+  variable `MFX_CALL_LOG` names a file, one line `{"status": 200, "ms": 12.5}` is appended to it
+  for each. A read retried after a 429 is two attempts. Nothing else is written: no path, id,
+  header or key. A listener that throws, or a file that cannot be written, never fails a call.
+  The platform's checks use it to count and time a sample's calls, as they do for the Python SDK.
+
+## 0.2.2
+
+### Fixed
+
+- `stream.close()` ends the stream for good. A `next()` or a `for await` loop waiting for a message
+  ends with nothing, and a reconnect under way is given up. Before, closing while a read waited
+  made the stream reconnect and keep delivering, so a script that closed its stream did not end.
+
 ## 0.2.1
 
 ### Added

package/dist/client.d.ts

@@ -1,10 +1,3 @@
-/**
- * `MfxClient`: one signed connection to the MFX Hub API.
- *
- * Every request is signed with the tenant's Ed25519 key. Reads that are rate limited are retried
- * after the platform's own `Retry-After`; writes are never retried, because a retried write is a
- * second order. Failures become typed errors from `errors.ts`.
- */
 import { MfxApiError } from "./errors.js";
 import { RequestSigner, type SigningKey } from "./signing.js";
 import { Accounts } from "./accounts.js";
@@ -16,6 +9,18 @@ import { Terminals } from "./terminals.js";
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 /** How many times a rate-limited read is tried again. */
 export declare const DEFAULT_READ_RETRIES = 3;
+/** The environment variable naming a file to append one JSON line to for every HTTP attempt. */
+export declare const CALL_LOG_ENV = "MFX_CALL_LOG";
+/**
+ * One HTTP attempt the client made: what was asked, the status, and how long it took.
+ * Each attempt is a call: a read retried after a 429 is two. `status` is null when no answer came
+ * (a connection that failed, a timeout). `ms` is measured on the client's own clock.
+ */
+export interface CallTiming {
+    readonly what: string;
+    readonly status: number | null;
+    readonly ms: number;
+}
 /** What the key had left when MFX Hub last answered. */
 export interface Budget {
     readonly remaining: number;
@@ -35,6 +40,10 @@ export interface ClientOptions {
     readonly clock?: () => number;
     /** A number in [0, 1) for the backoff's jitter; replaceable in tests. */
     readonly random?: () => number;
+    /** Told each call as it ends ({@link CallTiming}); `MFX_CALL_LOG` is the same, as a file. */
+    readonly onCall?: (timing: CallTiming) => void;
+    /** A monotonic clock in milliseconds; replaceable in tests. */
+    readonly now?: () => number;
 }
 /** One request, as the resource modules describe it. */
 export interface RequestSpec {

package/dist/client.js

@@ -5,6 +5,7 @@
  * after the platform's own `Retry-After`; writes are never retried, because a retried write is a
  * second order. Failures become typed errors from `errors.ts`.
  */
+import { appendFileSync } from "node:fs";
 import { MfxApiError, MfxTimeout, MfxTransportError, errorFor, retryAfterSeconds, } from "./errors.js";
 import { RequestSigner } from "./signing.js";
 import { Accounts } from "./accounts.js";
@@ -28,6 +29,8 @@ const NOT_SENT = new Set([
     "EHOSTUNREACH",
     "UND_ERR_CONNECT_TIMEOUT",
 ]);
+/** The environment variable naming a file to append one JSON line to for every HTTP attempt. */
+export const CALL_LOG_ENV = "MFX_CALL_LOG";
 const wait = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
@@ -40,6 +43,9 @@ export class MfxClient {
     #sleep;
     #fetch;
     #random;
+    #onCall;
+    #now;
+    #callLog;
     #budget = null;
     /** The terminals this key's tenant owns. */
     terminals;
@@ -63,6 +69,9 @@ export class MfxClient {
         this.#sleep = options.sleep ?? wait;
         this.#fetch = options.fetch ?? fetch;
         this.#random = options.random ?? Math.random;
+        this.#onCall = options.onCall;
+        this.#now = options.now ?? (() => performance.now());
+        this.#callLog = process.env[CALL_LOG_ENV] || undefined;
         this.terminals = new Terminals(this);
         this.execution = new Execution(this);
         this.catalog = new Catalog(this);
@@ -146,18 +155,29 @@ export class MfxClient {
             headers["Content-Type"] = "application/json";
         if (spec.idempotencyKey !== undefined)
             headers["Idempotency-Key"] = spec.idempotencyKey;
-        let response;
+        const started = this.#now();
+        let status = null;
         try {
-            response = await this.#fetch(url, {
-                method: spec.method,
-                headers,
-                ...(spec.body === undefined ? {} : { body }),
-                signal: AbortSignal.timeout(this.#timeoutMs),
-            });
+            let response;
+            try {
+                response = await this.#fetch(url, {
+                    method: spec.method,
+                    headers,
+                    ...(spec.body === undefined ? {} : { body }),
+                    signal: AbortSignal.timeout(this.#timeoutMs),
+                });
+            }
+            catch (error) {
+                throw transportError(error, spec);
+            }
+            status = response.status;
+            return await this.#answer(response);
         }
-        catch (error) {
-            throw transportError(error, spec);
+        finally {
+            this.#timed(`${spec.method} ${spec.path}`, status, started);
         }
+    }
+    async #answer(response) {
         const text = await response.text();
         this.#noteBudget(response.headers);
         let parsed = null;
@@ -171,6 +191,29 @@ export class MfxClient {
         }
         return { status: response.status, headers: response.headers, body: parsed };
     }
+    /**
+     * Hand one call's timing on. Never throws: timing is an observation, not a reason for a call
+     * that succeeded to fail. Nothing but the status and the time is written: no path, id, header
+     * or key.
+     */
+    #timed(what, status, started) {
+        const timing = { what, status, ms: this.#now() - started };
+        try {
+            this.#onCall?.(timing);
+        }
+        catch {
+            // A listener's bug must not fail the call.
+        }
+        if (this.#callLog !== undefined) {
+            try {
+                const ms = Math.round(timing.ms * 1000) / 1000;
+                appendFileSync(this.#callLog, JSON.stringify({ status, ms }) + "\n", "utf8");
+            }
+            catch {
+                // An unwritable log is no reason to fail a call.
+            }
+        }
+    }
     #noteBudget(headers) {
         const remaining = headers.get("X-MFX-Budget-Remaining");
         if (remaining !== null && Number.isFinite(Number(remaining))) {

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
  * ```
  */
-export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
-export type { Answer, Budget, ClientOptions, RequestSpec } from "./client.js";
+export { MfxClient, CALL_LOG_ENV, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
+export type { Answer, Budget, CallTiming, ClientOptions, RequestSpec } from "./client.js";
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";

package/dist/index.js

@@ -6,7 +6,7 @@
  * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
  * ```
  */
-export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
+export { MfxClient, CALL_LOG_ENV, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";

package/dist/stream.d.ts

@@ -127,7 +127,10 @@ export declare class MfxStream implements AsyncIterable<StreamEvent> {
     resume(channel: string): Promise<void>;
     /** Stop watching a channel, and stop subscribing to it again after a reconnect. */
     unsubscribe(channel: string): Promise<void>;
-    /** Close the connection, if one is open. */
+    /**
+     * Close the stream for good. A read waiting on it ends with null, a reconnect under way is
+     * given up, and the stream is never opened again.
+     */
     close(): Promise<void>;
     [Symbol.asyncIterator](): AsyncGenerator<StreamEvent, void, undefined>;
     /**

package/dist/stream.js

@@ -208,6 +208,8 @@ export class MfxStream {
         refused: 0,
     };
     #connection = null;
+    /** The caller closed the stream: nothing reconnects it, and every read is null from here on. */
+    #closed = false;
     /** Use {@link MfxClient.stream}. */
     constructor(client, options = {}) {
         this.#client = client;
@@ -258,8 +260,12 @@ export class MfxStream {
         this.#channels.delete(channel);
         await this.#send({ op: "unsubscribe", ch: channel });
     }
-    /** Close the connection, if one is open. */
+    /**
+     * Close the stream for good. A read waiting on it ends with null, a reconnect under way is
+     * given up, and the stream is never opened again.
+     */
     async close() {
+        this.#closed = true;
         const connection = this.#connection;
         this.#connection = null;
         if (connection !== null)
@@ -287,6 +293,9 @@ export class MfxStream {
                 raw = await connection.recv();
             }
             catch (error) {
+                // The caller's own close ends the read; it is not a drop to come back from.
+                if (this.#closed)
+                    return null;
                 if (!(error instanceof StreamClosed))
                     throw error;
                 if (!(await this.#reopen(error)))
@@ -362,7 +371,14 @@ export class MfxStream {
         this.#bump("reconnects");
         // The client's own backoff, so the stream and the reads lean on this tenant's quota alike.
         await this.#client.pause(this.#client.backoffMs(this.#stats.reconnects));
+        if (this.#closedNow())
+            return false; // closed while waiting out the backoff
         await this.open();
+        if (this.#closedNow()) {
+            // closed while the connection was being opened: that one is closed too
+            await this.close();
+            return false;
+        }
         for (const [channel, last] of [...this.#channels]) {
             if (replayable(channel) && last !== null) {
                 await this.#send({ op: "resume", ch: channel, after_seq: last });
@@ -376,6 +392,10 @@ export class MfxStream {
         }
         return true;
     }
+    /** Read afresh after an await: close() may have run while this was waiting. */
+    #closedNow() {
+        return this.#closed;
+    }
     async #send(message) {
         const connection = this.#connection;
         if (connection === null)

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This package's version. */
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.2.3";
 /** What every request says it is, as a product token: the SDK's language and its version. */
-export declare const USER_AGENT = "mfx-sdk-typescript/0.2.1";
+export declare const USER_AGENT = "mfx-sdk-typescript/0.2.3";

package/dist/version.js

@@ -1,5 +1,5 @@
 // This package's version, in one place: exported by the package, and named by every request.
 /** This package's version. */
-export const VERSION = "0.2.1";
+export const VERSION = "0.2.3";
 /** What every request says it is, as a product token: the SDK's language and its version. */
 export const USER_AGENT = `mfx-sdk-typescript/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfxhub/sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Typed TypeScript client for the MFX Hub API: hosted trading terminals, market data, execution and a live event stream",
   "license": "Apache-2.0",
   "type": "module",