@imbingox/acex 0.1.0-beta.2 → 0.1.0-beta.3

package/src/client/private-subscription-coordinator.ts

@@ -0,0 +1,512 @@
+import type {
+  PrivateUserDataAdapter,
+  StreamHandle,
+} from "../adapters/types.ts";
+import { AcexError } from "../errors.ts";
+import type { AccountRuntimeOptions, Exchange } from "../types/index.ts";
+import type {
+  ClientContext,
+  PrivateAccountDataConsumer,
+  PrivateOrderDataConsumer,
+  RegisteredAccountRecord,
+} from "./context.ts";
+
+interface PrivateSubscriptionRecord {
+  accountId: string;
+  exchange: Exchange;
+  accountSubscribed: boolean;
+  ordersSubscribed: boolean;
+  accountReady: boolean;
+  orderReady: boolean;
+  stream?: StreamHandle;
+  startPromise?: Promise<void>;
+  reconcilePromise?: Promise<void>;
+}
+
+const DEFAULT_STREAM_OPEN_TIMEOUT_MS = 15_000;
+const DEFAULT_STREAM_RECONNECT_DELAY_MS = 1_000;
+const DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS = 10_000;
+const DEFAULT_LISTEN_KEY_KEEPALIVE_MS = 30 * 60 * 1_000;
+
+export class PrivateSubscriptionCoordinator {
+  private readonly context: ClientContext;
+  private readonly adapter: PrivateUserDataAdapter;
+  private readonly accountConsumer: PrivateAccountDataConsumer;
+  private readonly orderConsumer: PrivateOrderDataConsumer;
+  private readonly streamOpenTimeoutMs: number;
+  private readonly streamReconnectDelayMs: number;
+  private readonly streamReconnectMaxDelayMs: number;
+  private readonly listenKeyKeepAliveMs: number;
+  private readonly records = new Map<string, PrivateSubscriptionRecord>();
+
+  constructor(
+    context: ClientContext,
+    adapter: PrivateUserDataAdapter,
+    accountConsumer: PrivateAccountDataConsumer,
+    orderConsumer: PrivateOrderDataConsumer,
+    options: AccountRuntimeOptions = {},
+  ) {
+    this.context = context;
+    this.adapter = adapter;
+    this.accountConsumer = accountConsumer;
+    this.orderConsumer = orderConsumer;
+    this.streamOpenTimeoutMs =
+      options.streamOpenTimeoutMs ?? DEFAULT_STREAM_OPEN_TIMEOUT_MS;
+    this.streamReconnectDelayMs =
+      options.streamReconnectDelayMs ?? DEFAULT_STREAM_RECONNECT_DELAY_MS;
+    this.streamReconnectMaxDelayMs =
+      options.streamReconnectMaxDelayMs ??
+      DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS;
+    this.listenKeyKeepAliveMs =
+      options.listenKeyKeepAliveMs ?? DEFAULT_LISTEN_KEY_KEEPALIVE_MS;
+  }
+
+  async subscribeAccountFeed(accountId: string): Promise<void> {
+    const account = this.getAccount(accountId);
+    const record = this.getOrCreateRecord(account);
+    const needsPending = !record.stream && !record.startPromise;
+    record.accountSubscribed = true;
+    if (needsPending) {
+      this.accountConsumer.onPrivateAccountPending(accountId, record.exchange);
+    }
+
+    try {
+      await this.ensureStream(record, account);
+      await this.bootstrapAccount(record, account);
+    } catch (error) {
+      record.accountSubscribed = false;
+      this.closeIfUnused(record);
+      throw error;
+    }
+  }
+
+  unsubscribeAccountFeed(accountId: string): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    record.accountSubscribed = false;
+    this.closeIfUnused(record);
+  }
+
+  async subscribeOrderFeed(accountId: string): Promise<void> {
+    const account = this.getAccount(accountId);
+    const record = this.getOrCreateRecord(account);
+    const needsPending = !record.stream && !record.startPromise;
+    record.ordersSubscribed = true;
+    if (needsPending) {
+      this.orderConsumer.onPrivateOrderPending(accountId, record.exchange);
+    }
+
+    try {
+      await this.ensureStream(record, account);
+      await this.bootstrapOrders(record, account);
+    } catch (error) {
+      record.ordersSubscribed = false;
+      this.closeIfUnused(record);
+      throw error;
+    }
+  }
+
+  unsubscribeOrderFeed(accountId: string): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    record.ordersSubscribed = false;
+    this.closeIfUnused(record);
+  }
+
+  onClientStarted(): void {
+    for (const record of this.records.values()) {
+      if (!this.isActive(record)) {
+        continue;
+      }
+
+      if (record.accountSubscribed) {
+        this.accountConsumer.onPrivateAccountPending(
+          record.accountId,
+          record.exchange,
+        );
+      }
+      if (record.ordersSubscribed) {
+        this.orderConsumer.onPrivateOrderPending(
+          record.accountId,
+          record.exchange,
+        );
+      }
+
+      void this.resumeRecord(record);
+    }
+  }
+
+  onClientStopping(): void {
+    for (const record of this.records.values()) {
+      this.closeStream(record);
+    }
+  }
+
+  onAccountRemoved(accountId: string): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    this.closeStream(record);
+    this.records.delete(accountId);
+  }
+
+  onCredentialsUpdated(accountId: string): void {
+    const record = this.records.get(accountId);
+    if (!record || !this.isActive(record)) {
+      return;
+    }
+
+    if (record.accountSubscribed) {
+      this.accountConsumer.onPrivateAccountPending(accountId, record.exchange);
+    }
+    if (record.ordersSubscribed) {
+      this.orderConsumer.onPrivateOrderPending(accountId, record.exchange);
+    }
+
+    void this.resumeRecord(record);
+  }
+
+  private async resumeRecord(record: PrivateSubscriptionRecord): Promise<void> {
+    const account = this.getAccount(record.accountId);
+    this.closeStream(record);
+
+    try {
+      await this.ensureStream(record, account);
+      if (record.accountSubscribed) {
+        await this.bootstrapAccount(record, account);
+      }
+      if (record.ordersSubscribed) {
+        await this.bootstrapOrders(record, account);
+      }
+    } catch {
+      // Errors are already published to the runtime error bus.
+    }
+  }
+
+  private getAccount(accountId: string): RegisteredAccountRecord {
+    const account = this.context.getRegisteredAccount(accountId);
+    if (account.exchange !== this.adapter.exchange) {
+      throw new AcexError(
+        "EXCHANGE_NOT_SUPPORTED",
+        `Exchange is not supported yet: ${account.exchange}`,
+      );
+    }
+
+    return account;
+  }
+
+  private getOrCreateRecord(
+    account: RegisteredAccountRecord,
+  ): PrivateSubscriptionRecord {
+    const existing = this.records.get(account.accountId);
+    if (existing) {
+      return existing;
+    }
+
+    const record: PrivateSubscriptionRecord = {
+      accountId: account.accountId,
+      exchange: account.exchange,
+      accountSubscribed: false,
+      ordersSubscribed: false,
+      accountReady: false,
+      orderReady: false,
+    };
+
+    this.records.set(account.accountId, record);
+    return record;
+  }
+
+  private isActive(record: PrivateSubscriptionRecord): boolean {
+    return record.accountSubscribed || record.ordersSubscribed;
+  }
+
+  private closeIfUnused(record: PrivateSubscriptionRecord): void {
+    if (this.isActive(record)) {
+      return;
+    }
+
+    this.closeStream(record);
+    this.records.delete(record.accountId);
+  }
+
+  private closeStream(record: PrivateSubscriptionRecord): void {
+    record.stream?.close();
+    record.stream = undefined;
+  }
+
+  private async ensureStream(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+  ): Promise<void> {
+    if (record.stream) {
+      return;
+    }
+
+    if (!record.startPromise) {
+      record.startPromise = this.startStream(record, account);
+    }
+
+    try {
+      await record.startPromise;
+    } finally {
+      if (record.startPromise) {
+        record.startPromise = undefined;
+      }
+    }
+  }
+
+  private async startStream(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+  ): Promise<void> {
+    const credentials = account.credentials;
+    if (!credentials) {
+      throw new AcexError(
+        "CREDENTIALS_MISSING",
+        `Account credentials are required for private subscriptions: ${account.accountId}`,
+      );
+    }
+
+    const stream = this.adapter.createPrivateStream(
+      credentials,
+      {
+        onAccountUpdate: (update) => {
+          if (!record.accountSubscribed) {
+            return;
+          }
+
+          record.accountReady = true;
+          this.accountConsumer.onPrivateAccountUpdate(
+            record.accountId,
+            record.exchange,
+            update,
+          );
+        },
+        onOrderUpdate: (update) => {
+          if (!record.ordersSubscribed) {
+            return;
+          }
+
+          record.orderReady = true;
+          this.orderConsumer.onPrivateOrderUpdate(
+            record.accountId,
+            record.exchange,
+            update,
+          );
+        },
+        onDisconnected: () => {
+          if (record.accountSubscribed) {
+            this.accountConsumer.onPrivateAccountStreamState(
+              record.accountId,
+              record.exchange,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.accountReady,
+                reason: "ws_disconnected",
+              },
+            );
+          }
+          if (record.ordersSubscribed) {
+            this.orderConsumer.onPrivateOrderStreamState(
+              record.accountId,
+              record.exchange,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.orderReady,
+                reason: "ws_disconnected",
+              },
+            );
+          }
+        },
+        onReconnected: () => {
+          if (!record.reconcilePromise) {
+            record.reconcilePromise = this.reconcileRecord(record)
+              .catch(() => {})
+              .finally(() => {
+                record.reconcilePromise = undefined;
+              });
+          }
+        },
+        onError: (error) => {
+          this.context.publishRuntimeError("adapter", error, {
+            accountId: record.accountId,
+            exchange: record.exchange,
+          });
+        },
+      },
+      {
+        openTimeoutMs: this.streamOpenTimeoutMs,
+        reconnectDelayMs: this.streamReconnectDelayMs,
+        reconnectMaxDelayMs: this.streamReconnectMaxDelayMs,
+        listenKeyKeepAliveMs: this.listenKeyKeepAliveMs,
+        now: () => this.context.now(),
+      },
+      account.options,
+    );
+
+    record.stream = stream;
+
+    try {
+      await stream.ready;
+    } catch (error) {
+      this.closeStream(record);
+      const runtimeError =
+        error instanceof Error
+          ? error
+          : new Error("Failed to open Binance private stream");
+      this.context.publishRuntimeError("adapter", runtimeError, {
+        accountId: record.accountId,
+        exchange: record.exchange,
+      });
+
+      if (record.accountSubscribed) {
+        this.accountConsumer.onPrivateAccountStreamState(
+          record.accountId,
+          record.exchange,
+          {
+            runtimeStatus: "degraded",
+            ready: record.accountReady,
+            reason: "ws_disconnected",
+          },
+        );
+      }
+      if (record.ordersSubscribed) {
+        this.orderConsumer.onPrivateOrderStreamState(
+          record.accountId,
+          record.exchange,
+          {
+            runtimeStatus: "degraded",
+            ready: record.orderReady,
+            reason: "ws_disconnected",
+          },
+        );
+      }
+
+      throw runtimeError;
+    }
+  }
+
+  private async reconcileRecord(
+    record: PrivateSubscriptionRecord,
+  ): Promise<void> {
+    const account = this.getAccount(record.accountId);
+
+    if (record.accountSubscribed) {
+      this.accountConsumer.onPrivateAccountPending(
+        record.accountId,
+        record.exchange,
+      );
+      await this.bootstrapAccount(record, account);
+    }
+
+    if (record.ordersSubscribed) {
+      this.orderConsumer.onPrivateOrderPending(
+        record.accountId,
+        record.exchange,
+      );
+      await this.bootstrapOrders(record, account);
+    }
+  }
+
+  private async bootstrapAccount(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+  ): Promise<void> {
+    try {
+      const bootstrap = await this.adapter.bootstrapAccount(
+        account.credentials ?? {},
+        account.options,
+      );
+      if (!record.accountSubscribed) {
+        return;
+      }
+
+      record.accountReady = true;
+      this.accountConsumer.onPrivateAccountBootstrap(
+        record.accountId,
+        record.exchange,
+        bootstrap,
+      );
+    } catch (error) {
+      record.accountReady = false;
+      this.context.publishRuntimeError(
+        "adapter",
+        error instanceof Error
+          ? error
+          : new Error("Failed to bootstrap Binance private account state"),
+        {
+          accountId: record.accountId,
+          exchange: record.exchange,
+        },
+      );
+      this.accountConsumer.onPrivateAccountStreamState(
+        record.accountId,
+        record.exchange,
+        {
+          runtimeStatus: "degraded",
+          ready: false,
+          reason: "auth_failed",
+        },
+      );
+      throw new AcexError(
+        "ACCOUNT_BOOTSTRAP_FAILED",
+        `Failed to bootstrap account data: ${record.accountId}`,
+      );
+    }
+  }
+
+  private async bootstrapOrders(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+  ): Promise<void> {
+    try {
+      const snapshots = await this.adapter.bootstrapOpenOrders(
+        account.credentials ?? {},
+        account.options,
+      );
+      if (!record.ordersSubscribed) {
+        return;
+      }
+
+      record.orderReady = true;
+      this.orderConsumer.onPrivateOrderBootstrap(
+        record.accountId,
+        record.exchange,
+        snapshots,
+      );
+    } catch (error) {
+      record.orderReady = false;
+      this.context.publishRuntimeError(
+        "adapter",
+        error instanceof Error
+          ? error
+          : new Error("Failed to bootstrap Binance private order state"),
+        {
+          accountId: record.accountId,
+          exchange: record.exchange,
+        },
+      );
+      this.orderConsumer.onPrivateOrderStreamState(
+        record.accountId,
+        record.exchange,
+        {
+          runtimeStatus: "degraded",
+          ready: false,
+          reason: "auth_failed",
+        },
+      );
+      throw new AcexError(
+        "ORDER_BOOTSTRAP_FAILED",
+        `Failed to bootstrap order data: ${record.accountId}`,
+      );
+    }
+  }
+}

package/src/client/runtime.ts

@@ -1,4 +1,12 @@
 import { BinanceMarketAdapter } from "../adapters/binance/adapter.ts";
+import { BinancePrivateAdapter } from "../adapters/binance/private-adapter.ts";
+import type {
+  CancelAllOrdersRequest,
+  CancelOrderRequest,
+  CreateOrderRequest,
+  PrivateUserDataAdapter,
+  RawOrderUpdate,
+} from "../adapters/types.ts";
 import { AcexError, type AcexErrorCode } from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
@@ -10,11 +18,14 @@ import type {
   AccountManager,
   AcexClient,
   AcexInternalError,
+  CancelAllOrdersInput,
+  CancelOrderInput,
   ClientEventStreams,
   ClientHealthSnapshot,
   ClientStatus,
   ClientStatusChangedEvent,
   CreateClientOptions,
+  CreateOrderInput,
   HealthEvent,
   HealthEventFilter,
   MarketManager,
@@ -27,8 +38,23 @@ import {
   type ClientContext,
   hasPrivateCredentials,
   mergeCredentials,
+  type PrivateAccountDataConsumer,
+  type PrivateOrderDataConsumer,
   type RegisteredAccountRecord,
 } from "./context.ts";
+import { PrivateSubscriptionCoordinator } from "./private-subscription-coordinator.ts";
+
+const activeClients = new Set<AcexClientImpl>();
+
+export function stopAllClientsForTests(): void {
+  const clients = [...activeClients];
+  activeClients.clear();
+  for (const client of clients) {
+    void client.stop().catch(() => {
+      // Test cleanup should be best-effort and never mask the original failure.
+    });
+  }
+}
 
 class ClientEventStreamsImpl implements ClientEventStreams {
   constructor(
@@ -61,11 +87,16 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   private readonly marketManager: MarketManagerImpl;
   private readonly accountManager: AccountManagerImpl;
   private readonly orderManager: OrderManagerImpl;
+  private readonly privateAdapter: PrivateUserDataAdapter;
+  private readonly privateCoordinator: PrivateSubscriptionCoordinator;
 
   constructor(options: CreateClientOptions = {}) {
-    const adapter = new BinanceMarketAdapter();
+    activeClients.add(this);
 
-    this.marketManager = new MarketManagerImpl(this, adapter, {
+    const marketAdapter = new BinanceMarketAdapter();
+    this.privateAdapter = new BinancePrivateAdapter();
+
+    this.marketManager = new MarketManagerImpl(this, marketAdapter, {
       initialL1TimeoutMs: options.market?.l1InitialMessageTimeoutMs,
       l1StaleAfterMs: options.market?.l1StaleAfterMs,
       l1ReconnectDelayMs: options.market?.l1ReconnectDelayMs,
@@ -73,6 +104,13 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     });
     this.accountManager = new AccountManagerImpl(this);
     this.orderManager = new OrderManagerImpl(this);
+    this.privateCoordinator = new PrivateSubscriptionCoordinator(
+      this,
+      this.privateAdapter,
+      this.accountManager as PrivateAccountDataConsumer,
+      this.orderManager as PrivateOrderDataConsumer,
+      options.account,
+    );
 
     this.market = this.marketManager;
     this.account = this.accountManager;
@@ -141,6 +179,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
 
     this.accountManager.onCredentialsUpdated(accountId, account.exchange);
     this.orderManager.onCredentialsUpdated(accountId, account.exchange);
+    this.privateCoordinator.onCredentialsUpdated(accountId);
   }
 
   async removeAccount(accountId: string): Promise<void> {
@@ -154,6 +193,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     }
 
     const now = this.now();
+    this.privateCoordinator.onAccountRemoved(accountId);
     this.accountManager.onAccountRemoved(accountId, now);
     this.orderManager.onAccountRemoved(accountId, now);
     this.registeredAccounts.delete(accountId);
@@ -170,6 +210,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     this.marketManager.onClientStarted();
     this.accountManager.onClientStarted();
     this.orderManager.onClientStarted();
+    this.privateCoordinator.onClientStarted();
   }
 
   async stop(_options?: StopOptions): Promise<void> {
@@ -183,6 +224,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     this.setClientStatus("stopping");
 
     const now = this.now();
+    this.privateCoordinator.onClientStopping();
     this.marketManager.onClientStopping(now);
     this.accountManager.onClientStopping(now);
     this.orderManager.onClientStopping(now);
@@ -231,6 +273,70 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     );
   }
 
+  subscribePrivateAccountFeed(accountId: string): Promise<void> {
+    return this.privateCoordinator.subscribeAccountFeed(accountId);
+  }
+
+  unsubscribePrivateAccountFeed(accountId: string): void {
+    this.privateCoordinator.unsubscribeAccountFeed(accountId);
+  }
+
+  subscribePrivateOrderFeed(accountId: string): Promise<void> {
+    return this.privateCoordinator.subscribeOrderFeed(accountId);
+  }
+
+  unsubscribePrivateOrderFeed(accountId: string): void {
+    this.privateCoordinator.unsubscribeOrderFeed(accountId);
+  }
+
+  createOrder(input: CreateOrderInput): Promise<RawOrderUpdate> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CreateOrderRequest = {
+      symbol: input.symbol,
+      side: input.side,
+      type: input.type,
+      amount: input.amount,
+      price: input.type === "limit" ? input.price : undefined,
+      clientOrderId: input.clientOrderId,
+      reduceOnly: input.reduceOnly,
+      positionSide: input.positionSide,
+    };
+
+    return this.privateAdapter.createOrder(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
+  cancelOrder(input: CancelOrderInput): Promise<RawOrderUpdate> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CancelOrderRequest = {
+      symbol: input.symbol,
+      orderId: input.orderId,
+      clientOrderId: input.clientOrderId,
+    };
+
+    return this.privateAdapter.cancelOrder(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
+  cancelAllOrders(input: CancelAllOrdersInput): Promise<RawOrderUpdate[]> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CancelAllOrdersRequest = {
+      symbol: input.symbol,
+    };
+
+    return this.privateAdapter.cancelAllOrders(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
   publishRuntimeError(
     source: AcexInternalError["source"],
     error: Error,
@@ -280,4 +386,25 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     });
     return error;
   }
+
+  private getPrivateCommandAccount(accountId: string): RegisteredAccountRecord {
+    const account = this.getRegisteredAccount(accountId);
+    if (account.exchange !== this.privateAdapter.exchange) {
+      throw this.createError(
+        "EXCHANGE_NOT_SUPPORTED",
+        `Exchange is not supported yet: ${account.exchange}`,
+        { accountId, exchange: account.exchange },
+      );
+    }
+
+    if (!hasPrivateCredentials(account.credentials)) {
+      throw this.createError(
+        "CREDENTIALS_MISSING",
+        `Account credentials are required for private order commands: ${accountId}`,
+        { accountId, exchange: account.exchange },
+      );
+    }
+
+    return account;
+  }
 }