@imbingox/acex 0.4.0-beta.5 → 0.4.0-beta.7

package/docs/api.md

@@ -345,6 +345,7 @@ interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
   listMarkets(venue?: Venue): MarketDefinition[];
   getMarket(venue: Venue, symbol: string): MarketDefinition | undefined;
   getMarkets(symbol: string): MarketDefinition[];
@@ -368,6 +369,7 @@ interface MarketManager {
 
 ```ts
 await client.market.loadMarkets();
+const reloadSummaries = await client.market.reloadMarkets("binance");
 
 const all = client.market.listMarkets();
 const binanceOnly = client.market.listMarkets("binance");
@@ -378,6 +380,25 @@ const allBtcPerp = client.market.getMarkets("BTC/USDT:USDT");
 
 `getMarkets(symbol)` 严格按完整统一 symbol 匹配。
 
+`loadMarkets()` 会懒加载并缓存当前已注册 venue 的市场目录；已加载过的 venue 不会重复拉取。`reloadMarkets(venue?)` 用于主动刷新市场目录：传入 `venue` 时只刷新该 venue，省略时刷新所有已注册 market adapter。它和 `loadMarkets()` 一样不要求 client 已 `start()`，因此可在 `start()` 前或 `stop()` 后调用。
+
+`reloadMarkets()` 返回每个 venue 的刷新摘要：
+
+```ts
+type MarketCatalogReloadSummary = {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+};
+```
+
+`added` / `removed` 是本次刷新相对旧目录变化的 symbol 列表，`total` 是刷新后该 venue 的目录数量。catalog 拉取失败时，对应 summary 为 `ok: false`，`error.code = "MARKET_CATALOG_LOAD_FAILED"`，旧目录会保留，方法不会因为该 venue 的 catalog 失败而 reject；未注册 runtime adapter 的合法 venue（例如当前 market adapter 未接入的 `bybit`）仍会抛 `VENUE_NOT_SUPPORTED`。
+
+如果刷新会新增 symbol，调用方应先 `await client.market.reloadMarkets(venue)`，再按 summary 订阅新增 symbol。已加载 venue 上的后台 reload 不会阻塞并发 `subscribe*()`；reload 完成前订阅新增 symbol 仍可能按旧目录返回 `MARKET_NOT_FOUND`。
+
 `MarketDefinition` 见 [§9](#9-数据类型参考)。价格/数量相关字段（`priceStep`、`amountStep`、`contractSize`、`minAmount`、`minNotional`）都是 canonical decimal string；需要运算时用 `new BigNumber(field)` 自行解析。
 
 归一化下单价格和数量：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.5",
+  "version": "0.4.0-beta.7",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/adapters/binance/adapter.ts

@@ -3,6 +3,7 @@ import type {
   MarketDefinition,
   RateLimiter,
   VenueMarketCapabilities,
+  VenueServerTime,
 } from "../../types/index.ts";
 import type {
   FundingRateStreamCallbacks,
@@ -16,6 +17,7 @@ import {
   type BinanceMarketDefinition,
   loadBinanceMarkets,
 } from "./market-catalog.ts";
+import { fetchBinanceServerTime } from "./server-time.ts";
 import {
   type BinanceStreamDescriptor,
   type BinanceStreamMessage,
@@ -45,6 +47,7 @@ export class BinanceMarketAdapter implements MarketAdapter {
   readonly venue = "binance" as const;
   readonly marketCapabilities: VenueMarketCapabilities = {
     catalog: "supported",
+    serverTime: "supported",
     l1Book: "supported",
     fundingRate: "market_dependent",
     marketTypes: ["spot", "swap", "future"],
@@ -73,6 +76,12 @@ export class BinanceMarketAdapter implements MarketAdapter {
     return markets;
   }
 
+  async fetchServerTime(): Promise<VenueServerTime> {
+    return await fetchBinanceServerTime({
+      rateLimiter: this.options.rateLimiter,
+    });
+  }
+
   createL1BookStream(
     market: MarketDefinition,
     callbacks: L1BookStreamCallbacks,

package/src/adapters/binance/server-time.ts

@@ -0,0 +1,106 @@
+import {
+  type HttpClientMessages,
+  httpRequest,
+  isTransportError,
+} from "../../internal/http-client.ts";
+import type {
+  RateLimiter,
+  RateLimitScope,
+  VenueServerTime,
+} from "../../types/index.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+interface BinanceServerTimeResponse {
+  serverTime?: unknown;
+}
+
+export interface FetchBinanceServerTimeOptions {
+  readonly rateLimiter?: RateLimiter;
+  readonly fetchFn?: FetchLike;
+  readonly now?: () => number;
+  readonly monotonicNow?: () => number;
+}
+
+const BINANCE_USDM_SERVER_TIME_URL = "https://fapi.binance.com/fapi/v1/time";
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+const BINANCE_SERVER_TIME_HTTP_MESSAGES: HttpClientMessages = {
+  http: ({ status, statusText }) =>
+    `Binance server time request failed: ${status} ${statusText ?? ""}`,
+};
+
+export async function fetchBinanceServerTime(
+  options: FetchBinanceServerTimeOptions = {},
+): Promise<VenueServerTime> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const now = options.now ?? Date.now;
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
+  const scope: RateLimitScope = {
+    venue: "binance",
+    endpointKey: "GET /fapi/v1/time",
+  };
+
+  await options.rateLimiter?.beforeRequest({ scope });
+
+  const requestSentAt = now();
+  const startMono = monotonicNow();
+
+  try {
+    const response = await httpRequest<BinanceServerTimeResponse>({
+      fetchFn,
+      url: BINANCE_USDM_SERVER_TIME_URL,
+      timeoutMs: DEFAULT_HTTP_TIMEOUT_MS,
+      parseAs: "json",
+      jsonParseMode: "response",
+      retryPolicy: {
+        idempotent: true,
+        maxAttempts: 1,
+      },
+      messages: BINANCE_SERVER_TIME_HTTP_MESSAGES,
+    });
+    const responseReceivedAt = now();
+    const endMono = monotonicNow();
+
+    await options.rateLimiter?.afterResponse(
+      { scope },
+      {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+      },
+    );
+
+    const { serverTime } = response.body;
+    if (typeof serverTime !== "number" || !Number.isFinite(serverTime)) {
+      throw new Error(
+        "Binance server time response missing numeric serverTime",
+      );
+    }
+
+    return {
+      serverTime,
+      requestSentAt,
+      responseReceivedAt,
+      roundTripMs: endMono - startMono,
+      estimatedOffsetMs: serverTime - (requestSentAt + responseReceivedAt) / 2,
+    };
+  } catch (error) {
+    if (isTransportError(error)) {
+      await options.rateLimiter?.onTransportError(
+        { scope },
+        {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+        },
+      );
+    }
+
+    throw error;
+  }
+}

package/src/adapters/types.ts

@@ -9,6 +9,7 @@ import type {
   VenueAccountCapabilities,
   VenueMarketCapabilities,
   VenueOrderCapabilities,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface StreamHandle {
@@ -74,6 +75,7 @@ export interface MarketAdapter {
   readonly venue: Venue;
   readonly marketCapabilities: VenueMarketCapabilities;
   loadMarkets(): Promise<MarketDefinition[]>;
+  fetchServerTime?(): Promise<VenueServerTime>;
   createL1BookStream(
     market: MarketDefinition,
     callbacks: L1BookStreamCallbacks,

package/src/client/venue-capabilities.ts

@@ -42,6 +42,7 @@ const typeOnlyNotes = [
 
 const unsupportedMarket: VenueMarketCapabilities = {
   catalog: "unsupported",
+  serverTime: "unsupported",
   l1Book: "unsupported",
   fundingRate: "unsupported",
   marketTypes: [],

package/src/errors.ts

@@ -6,6 +6,7 @@ export type AcexErrorCode =
   | "CREDENTIALS_MISSING"
   | "VENUE_NOT_SUPPORTED"
   | "MARKET_CATALOG_LOAD_FAILED"
+  | "MARKET_SERVER_TIME_FETCH_FAILED"
   | "MARKET_INACTIVE"
   | "MARKET_FUNDING_RATE_UNSUPPORTED"
   | "MARKET_NOT_FOUND"

package/src/managers/market-manager.ts

@@ -23,6 +23,7 @@ import type {
   FundingRateUpdatedEvent,
   L1Book,
   L1BookUpdatedEvent,
+  MarketCatalogReloadSummary,
   MarketDataStatus,
   MarketDataStreamStatus,
   MarketDefinition,
@@ -37,6 +38,7 @@ import type {
   SubscribeL1BookInput,
   SubscriptionActivity,
   Venue,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface MarketManagerOptions {
@@ -63,6 +65,13 @@ interface MarketRecord {
   fundingRateStream?: StreamHandle;
 }
 
+interface CatalogFetchResult {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+}
+
 const DEFAULT_INITIAL_L1_TIMEOUT_MS = 15_000;
 const DEFAULT_L1_STALE_AFTER_MS = 15_000;
 const DEFAULT_L1_RECONNECT_DELAY_MS = 1_000;
@@ -114,7 +123,10 @@ export class MarketManagerImpl
   private readonly definitions = new Map<string, MarketDefinition>();
   private readonly records = new Map<string, MarketRecord>();
   private readonly loadedCatalogVenues = new Set<Venue>();
-  private readonly catalogPromises = new Map<Venue, Promise<void>>();
+  private readonly catalogPromises = new Map<
+    Venue,
+    Promise<CatalogFetchResult>
+  >();
   private readonly initialL1TimeoutMs: number;
   private readonly l1StaleAfterMs: number;
   private readonly l1ReconnectDelayMs: number;
@@ -166,6 +178,48 @@ export class MarketManagerImpl
     );
   }
 
+  async reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]> {
+    if (venue !== undefined) {
+      this.assertSupportedVenue(venue);
+      return [await this.reloadVenue(venue)];
+    }
+
+    const venues = [...this.adapters.keys()];
+    const settled = await Promise.allSettled(
+      venues.map((registeredVenue) => this.reloadVenue(registeredVenue)),
+    );
+    const summaries: MarketCatalogReloadSummary[] = [];
+
+    for (const result of settled) {
+      if (result.status === "fulfilled") {
+        summaries.push(result.value);
+        continue;
+      }
+
+      throw result.reason;
+    }
+
+    return summaries;
+  }
+
+  async fetchServerTime(venue: Venue): Promise<VenueServerTime> {
+    const adapter = this.getMarketAdapter(venue);
+    if (!adapter.fetchServerTime) {
+      throw this.createError(
+        "VENUE_NOT_SUPPORTED",
+        `Venue is not supported yet: ${venue}`,
+        { venue },
+        "client",
+      );
+    }
+
+    try {
+      return await adapter.fetchServerTime();
+    } catch (error) {
+      throw this.createServerTimeFetchError(venue, error);
+    }
+  }
+
   async subscribeL1Book(input: SubscribeL1BookInput): Promise<void> {
     this.context.assertStarted();
     const market = await this.resolveMarketDefinition(input);
@@ -438,51 +492,147 @@ export class MarketManagerImpl
       return;
     }
 
-    let catalogPromise = this.catalogPromises.get(venue);
-    if (!catalogPromise) {
-      catalogPromise = this.fetchAndStoreMarketCatalog(venue);
-      this.catalogPromises.set(venue, catalogPromise);
-    }
+    await this.fetchCatalogCoalesced(venue);
+  }
 
+  private async reloadVenue(venue: Venue): Promise<MarketCatalogReloadSummary> {
     try {
-      await catalogPromise;
+      const result = await this.fetchCatalogCoalesced(venue);
+      return { ...result, ok: true };
     } catch (error) {
-      this.catalogPromises.delete(venue);
+      if (
+        error instanceof AcexError &&
+        error.code === "MARKET_CATALOG_LOAD_FAILED"
+      ) {
+        return {
+          venue,
+          added: [],
+          removed: [],
+          total: this.countVenueMarkets(venue),
+          ok: false,
+          error,
+        };
+      }
+
       throw error;
     }
   }
 
-  private async fetchAndStoreMarketCatalog(venue: Venue): Promise<void> {
+  private async fetchCatalogCoalesced(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
+    let catalogPromise = this.catalogPromises.get(venue);
+    if (!catalogPromise) {
+      catalogPromise = this.fetchAndStoreMarketCatalog(venue).finally(() => {
+        this.catalogPromises.delete(venue);
+      });
+      this.catalogPromises.set(venue, catalogPromise);
+    }
+
+    return await catalogPromise;
+  }
+
+  private async fetchAndStoreMarketCatalog(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
     const adapter = this.getMarketAdapter(venue);
+    let markets: MarketDefinition[];
 
     try {
-      const markets = await adapter.loadMarkets();
+      markets = await adapter.loadMarkets();
+    } catch (error) {
+      throw this.createCatalogLoadError(venue, error);
+    }
 
-      for (const [key, market] of this.definitions) {
-        if (market.venue === venue) {
-          this.definitions.delete(key);
-        }
-      }
+    const mismatchedMarket = markets.find((market) => market.venue !== venue);
+    if (mismatchedMarket) {
+      throw this.createCatalogLoadError(
+        venue,
+        new Error(
+          `Market catalog from ${venue} included ${mismatchedMarket.venue} market: ${mismatchedMarket.symbol}`,
+        ),
+      );
+    }
 
-      for (const market of markets) {
-        this.definitions.set(marketKey(market), market);
+    const previousKeys = this.getVenueMarketKeys(venue);
+
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        this.definitions.delete(key);
       }
+    }
 
-      this.loadedCatalogVenues.add(venue);
-    } catch (error) {
-      const wrapped = new AcexError(
-        "MARKET_CATALOG_LOAD_FAILED",
-        `Failed to load market catalog from ${venue}`,
-      );
-      this.context.publishRuntimeError(
-        "adapter",
-        error instanceof Error
-          ? error
-          : new Error("Unknown catalog load failure"),
-        { venue },
-      );
-      throw wrapped;
+    for (const market of markets) {
+      this.definitions.set(marketKey(market), market);
     }
+
+    this.loadedCatalogVenues.add(venue);
+
+    const currentKeys = this.getVenueMarketKeys(venue);
+    return {
+      venue,
+      added: this.diffMarketSymbols(venue, currentKeys, previousKeys),
+      removed: this.diffMarketSymbols(venue, previousKeys, currentKeys),
+      total: currentKeys.size,
+    };
+  }
+
+  private getVenueMarketKeys(venue: Venue): Set<string> {
+    const keys = new Set<string>();
+
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        keys.add(key);
+      }
+    }
+
+    return keys;
+  }
+
+  private countVenueMarkets(venue: Venue): number {
+    return this.getVenueMarketKeys(venue).size;
+  }
+
+  private diffMarketSymbols(
+    venue: Venue,
+    left: Set<string>,
+    right: Set<string>,
+  ): string[] {
+    const prefix = `${venue}:`;
+    return [...left]
+      .filter((key) => !right.has(key))
+      .map((key) => key.slice(prefix.length))
+      .sort((leftSymbol, rightSymbol) => leftSymbol.localeCompare(rightSymbol));
+  }
+
+  private createCatalogLoadError(venue: Venue, error: unknown): AcexError {
+    const wrapped = new AcexError(
+      "MARKET_CATALOG_LOAD_FAILED",
+      `Failed to load market catalog from ${venue}`,
+    );
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error("Unknown catalog load failure"),
+      { venue },
+    );
+    return wrapped;
+  }
+
+  private createServerTimeFetchError(venue: Venue, error: unknown): AcexError {
+    const wrapped = new AcexError(
+      "MARKET_SERVER_TIME_FETCH_FAILED",
+      `Failed to fetch server time from ${venue}`,
+    );
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error("Unknown server time fetch failure"),
+      { venue },
+    );
+    return wrapped;
   }
 
   private async resolveMarketDefinition(input: {

package/src/types/client.ts

@@ -83,6 +83,7 @@ export type OrderTimeInForceCapability = "gtc" | "post_only";
 
 export interface VenueMarketCapabilities {
   catalog: VenueCapabilitySupport;
+  serverTime: VenueCapabilitySupport;
   l1Book: VenueCapabilitySupport;
   fundingRate: FundingRateCapability;
   marketTypes: MarketType[];

package/src/types/market.ts

@@ -1,4 +1,5 @@
 import type BigNumber from "bignumber.js";
+import type { AcexError } from "../errors.ts";
 import type { MarketFreshness, SubscriptionActivity, Venue } from "./shared.ts";
 
 export type MarketType = "spot" | "swap" | "future";
@@ -26,6 +27,28 @@ export interface MarketDefinition {
   raw: Record<string, unknown>;
 }
 
+export interface MarketCatalogReloadSummary {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+}
+
+export interface VenueServerTime {
+  /** Exchange server time in epoch milliseconds. Binance currently measures the USDM cluster. */
+  serverTime: number;
+  /** Local wall-clock timestamp captured immediately before the HTTP request is sent. */
+  requestSentAt: number;
+  /** Local wall-clock timestamp captured immediately after the HTTP response is received. */
+  responseReceivedAt: number;
+  /** Round trip duration measured with a monotonic clock, in milliseconds. */
+  roundTripMs: number;
+  /** NTP-style offset estimate: serverTime - midpoint(requestSentAt, responseReceivedAt). */
+  estimatedOffsetMs: number;
+}
+
 export interface MarketDataStatus {
   venue: Venue;
   symbol: string;
@@ -159,6 +182,8 @@ export interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
+  fetchServerTime(venue: Venue): Promise<VenueServerTime>;
   subscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   unsubscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;