@2702rebels/ntcore 1.0.0

package/src/NT4Client.ts

@@ -0,0 +1,935 @@
+import { Decoder, Encoder } from "@msgpack/msgpack";
+
+import { Logger } from "@2702rebels/logger";
+
+import { DataTypeCodes, NetworkSpecs } from "./NT4Spec";
+import { NT4Subscription } from "./NT4Subscription";
+import { NT4Topic } from "./NT4Topic";
+import { NT4WebSocketAsync } from "./NT4WebSocketAsync";
+
+import type { DataType, TextDataFrame } from "./NT4Spec";
+import type { SubscriptionOptions, TopicProperties } from "./NT4Types";
+
+export type NT4ClientConnectionState = "disconnected" | "connecting" | "connected";
+
+export type NT4ClientOptions = {
+  /** Indicates that secure channel should be used. */
+  secure?: boolean;
+
+  /**
+   * Invoked when the client connects.
+   */
+  onConnect?: () => void;
+
+  /**
+   * Invoked when the client disconnects.
+   */
+  onDisconnect?: () => void;
+
+  /**
+   * Invoked when new topic is announced by the server.
+   *
+   * @param topic topic announced
+   */
+  onTopicAnnounced?: (topic: NT4Topic) => void;
+
+  /**
+   * Invoked when a topic is removed by the server.
+   *
+   * @param topic topic removed
+   */
+  onTopicRemoved?: (topic: NT4Topic) => void;
+
+  /**
+   * Invoked when a topic properties are updated by the server.
+   *
+   * @param topic topic updated
+   */
+  onTopicUpdated?: (topic: NT4Topic) => void;
+
+  /**
+   * Invoked when the topic receives new data.
+   *
+   * @param topic topic receiving data
+   * @param value value received
+   * @param timestamp server timestamp in microseconds
+   */
+  onDataReceived?: (topic: NT4Topic, value: unknown, timestamp: number) => void;
+
+  /**
+   * Retry policy that accepts the current number of connection attempts
+   * and returns the timeout in milliseconds or -1 to abort.
+   *
+   * @param attempts number of subsequent connection attempts
+   * @returns timeout in milliseconds or -1 to abort
+   */
+  retryPolicy?: (attempts: number) => number;
+
+  /**
+   * Overrides default timeout for ping-pong packets.
+   *
+   * Defaults:
+   * - NT 4.0: 3000 milliseconds
+   * - NT 4.1: 1000 milliseconds
+   */
+  pingTimeoutMilliseconds?: number;
+};
+
+/** Determines whether the specified predicate callback returns true for any element of a map. */
+function some<K, V>(map: Map<K, V>, predicate: (entry: V) => boolean) {
+  for (const v of map.values()) {
+    if (predicate(v)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Implements a NetworkTable4 client that is responsible for establishing and maintaining a connection.
+ */
+export class NT4Client {
+  private readonly port: number;
+  private readonly clientId: string;
+  private readonly dataChannel: NT4WebSocketAsync;
+  private readonly rttChannel: NT4WebSocketAsync;
+  private readonly decoder = new Decoder();
+  private readonly encoder = new Encoder();
+  private readonly onConnect?: NT4ClientOptions["onConnect"];
+  private readonly onDisconnect?: NT4ClientOptions["onDisconnect"];
+  private readonly onTopicAnnounced?: NT4ClientOptions["onTopicAnnounced"];
+  private readonly onTopicRemoved?: NT4ClientOptions["onTopicRemoved"];
+  private readonly onTopicUpdated?: NT4ClientOptions["onTopicUpdated"];
+  private readonly onDataReceived?: NT4ClientOptions["onDataReceived"];
+  private readonly retryPolicy: Required<NT4ClientOptions>["retryPolicy"];
+  private pingTimeoutOverride_ms?: NT4ClientOptions["pingTimeoutMilliseconds"];
+
+  private subscriptions = new Map<number, NT4Subscription>();
+  private publishedTopics = new Map<string, NT4Topic>();
+  private announcedTopics = new Map<string, NT4Topic>();
+  private announcedTopicsIndex = new Map<number, NT4Topic>();
+
+  private connectionEstablished = false;
+  private connectionInitiated = false;
+  private connectionAttempts = 0;
+  private connectionState: NT4ClientConnectionState = "disconnected";
+  private networkLatency_μs: number | null = null;
+  private serverTimeOffset_μs: number | null = null;
+  private pingTimeout_ms = 0;
+  private pongTimestamp_μs = 0;
+  private pingIntervalId: ReturnType<typeof setInterval> | null = null;
+  private pongIntervalId: ReturnType<typeof setInterval> | null = null;
+
+  /** Truncated at 15 seconds exponential backoff retry policy starting at 1 second. */
+  public static defaultRetryPolicy(attempts: number) {
+    return Math.round(Math.min(15, Math.max(1, 1.2 ** Math.min(15, attempts))) * 1000);
+  }
+
+  /** Cleans up closed data channel. */
+  private cleanup() {
+    Logger.Default.debug(`[NT4Client] cleaning up`);
+
+    if (this.pingIntervalId) {
+      clearInterval(this.pingIntervalId);
+      this.pingIntervalId = null;
+    }
+
+    if (this.pongIntervalId) {
+      clearInterval(this.pongIntervalId);
+      this.pongIntervalId = null;
+    }
+
+    this.rttChannel.close();
+
+    if (this.connectionEstablished && this.onDisconnect) {
+      this.onDisconnect();
+    }
+
+    this.connectionEstablished = false;
+    this.connectionState = "disconnected";
+
+    this.announcedTopics.clear();
+    this.announcedTopicsIndex.clear();
+
+    for (const topic of this.publishedTopics.values()) {
+      topic.resetRetainedTimestamp();
+    }
+
+    this.pongTimestamp_μs = 0;
+    this.serverTimeOffset_μs = null;
+    this.networkLatency_μs = null;
+  }
+
+  /** Attempts to establish a connection, continuously retrying using policy. */
+  private async connectWithRetry() {
+    this.connectionState = "connecting";
+
+    // check for cancellation after each await, since disconnect could have been called
+    // while we were awaiting and therefore we should abort here or below
+    if (!this.connectionInitiated) {
+      Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+      return;
+    }
+
+    // probe remote endpoint status (liveness check)
+    let response: Response | null = null;
+    try {
+      response = await fetch(`http://${this.serverAddress}:${this.port}`, {
+        signal: AbortSignal.timeout(250),
+      });
+    } catch {
+      // swallow exception here; we are checking for response status below
+    }
+
+    if (!this.connectionInitiated) {
+      Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+      return;
+    }
+
+    // if endpoint seems to be alive try to establish websocket connection,
+    // otherwise, wait and retry again
+    if (response && response.ok) {
+      try {
+        Logger.Default.debug(`[NT4Client] opening channel to ${this.serverAddress}:${this.port}`);
+        await this.dataChannel.connect();
+
+        // reset connection attempts once the data channel is successfully connected
+        this.connectionAttempts = 0;
+
+        if (!this.connectionInitiated) {
+          Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+          return;
+        }
+
+        this.connectionEstablished = true;
+        this.connectionState = "connected";
+
+        Logger.Default.debug(
+          `[NT4Client] connected to ${this.serverAddress}:${this.port}, subprotocol = ${this.dataChannel.protocol}`
+        );
+
+        let pingPeriod_ms = NetworkSpecs.pingPeriod40;
+        this.pingTimeout_ms = this.pingTimeoutOverride_ms ?? NetworkSpecs.pingTimeout40;
+
+        if (this.dataChannel.protocol === NetworkSpecs.protocol41) {
+          Logger.Default.debug(`[NT4Client] server speaks v4.1, creating separate RTT channel`);
+          await this.rttChannel.connect();
+
+          if (!this.connectionInitiated) {
+            Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+            return;
+          }
+
+          pingPeriod_ms = NetworkSpecs.pingPeriod41;
+          this.pingTimeout_ms = this.pingTimeoutOverride_ms ?? NetworkSpecs.pingTimeout41;
+        }
+
+        Logger.Default.debug(`[NT4Client] sending timestamp and re-establishing subscriptions`);
+
+        // send timestamp to establish RTT
+        this.sendRTT();
+
+        // and start periodic ping
+        this.pongTimestamp_μs = 0;
+        this.pingIntervalId = setInterval(() => this.sendRTT(), pingPeriod_ms);
+        this.pongIntervalId = setInterval(() => this.checkTimeout(), pingPeriod_ms);
+
+        // restore client subscriptions
+        for (const subscription of this.subscriptions.values()) {
+          this.subscribeCore(subscription);
+        }
+
+        // restore client publishers
+        // retained values won't be sent until clock is synchronized
+        for (const topic of this.publishedTopics.values()) {
+          this.publishCore(topic);
+        }
+
+        if (this.onConnect) {
+          this.onConnect();
+        }
+
+        return;
+      } catch (exception) {
+        Logger.Default.error(`[NT4Client] failed to open channel`, exception);
+
+        await this.rttChannel.close();
+        await this.dataChannel.close();
+      }
+    }
+
+    // retry logic
+    this.connectionAttempts++;
+    const timeout = this.retryPolicy(this.connectionAttempts);
+
+    if (timeout < 0) {
+      Logger.Default.debug(`[NT4Client] aborting per retry policy after ${this.connectionAttempts} attempts`);
+      this.disconnect();
+      return;
+    }
+
+    Logger.Default.debug(`[NT4Client] retrying connection in ${timeout.toFixed(0)}ms`);
+    setTimeout(() => this.connectWithRetry(), timeout);
+  }
+
+  /** Invoked once the client-server clock is synchronized. */
+  private onClockSynchronized() {
+    Logger.Default.debug(`[NT4Client] clock synchronized, offset = ${this.serverTimeOffset_μs}`);
+
+    for (const topic of this.publishedTopics.values()) {
+      if (topic.retainedTimestamp != null && topic.retainedValue != null) {
+        this.sendValueCore(
+          topic,
+          topic.retainedValue,
+          topic.retainedTimestamp === 1 ? (this.serverTimeMicroseconds() ?? 1) : topic.retainedTimestamp
+        );
+      }
+    }
+  }
+
+  /** Consumes received data frame. */
+  private processDataFrame(data: string | BufferSource) {
+    if (typeof data === "string") {
+      let array: Array<TextDataFrame> | undefined;
+      try {
+        array = JSON.parse(data);
+        if (!Array.isArray(array)) {
+          Logger.Default.error(`[NT4Client] unexpected text frame, JSON must be an array, frame ignored`);
+          return;
+        }
+      } catch (exception) {
+        Logger.Default.error(`[NT4Client] unexpected text frame, JSON is malformed, frame ignored`, exception);
+        return;
+      }
+
+      array.forEach((d) => {
+        if (typeof d !== "object" || !("method" in d) || !("params" in d)) {
+          Logger.Default.error(`[NT4Client] malformed message in text frame, message ignored`);
+          return;
+        }
+
+        const { method, params } = d;
+        if (typeof method !== "string" || typeof params !== "object") {
+          Logger.Default.error(`[NT4Client] malformed message in text frame, message ignored`);
+          return;
+        }
+
+        switch (method) {
+          case "announce": {
+            const topic = new NT4Topic(params.id, params.name, params.type, params.properties, params.pubuid);
+            this.announcedTopics.set(topic.name, topic);
+            this.announcedTopicsIndex.set(topic.uid, topic);
+
+            if (this.onTopicAnnounced) {
+              this.onTopicAnnounced(topic);
+            }
+            return;
+          }
+
+          case "unannounce": {
+            const topic = this.announcedTopics.get(params.name);
+
+            // ignore topics that we haven't seen being announced
+            if (topic) {
+              this.publishedTopics.get(topic.name)?.removeRetainedValue();
+              this.announcedTopics.delete(topic.name);
+              this.announcedTopicsIndex.delete(topic.uid);
+
+              if (this.onTopicRemoved) {
+                this.onTopicRemoved(topic);
+              }
+            }
+            return;
+          }
+
+          case "properties": {
+            const topic = this.announcedTopics.get(params.name);
+            // ignore topics that we haven't seen being announced
+            if (topic) {
+              // https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#properties-update-message-properties
+              // The client shall handle the update value as follows.
+              // If a property is not included in the update map, its value is not changed.
+              // If a property is provided in the update map with a value of null, the property is deleted.
+              topic.mergeProperties(params.update);
+
+              if (this.onTopicUpdated) {
+                this.onTopicUpdated(topic);
+              }
+            }
+            return;
+          }
+
+          default:
+            Logger.Default.error(`[NT4Client] unexpected method '${method}' in text frame message, message ignored`);
+            return;
+        }
+      });
+    } else {
+      for (const d of this.decoder.decodeMulti(data)) {
+        const [topicId, timestamp, typeCode, value] = d as [number, number, number, unknown];
+
+        // sanity checks
+        if (typeof topicId !== "number") {
+          Logger.Default.error(`[NT4Client] unexpected non-numeric topic identifier, frame ignored`);
+          return;
+        }
+
+        if (typeof timestamp !== "number") {
+          Logger.Default.error(`[NT4Client] unexpected non-numeric timestamp, frame ignored`);
+          return;
+        }
+
+        if (typeof typeCode !== "number") {
+          Logger.Default.error(`[NT4Client] unexpected non-numeric typeCode, frame ignored`);
+          return;
+        }
+
+        if (topicId === -1) {
+          // RTT measurement
+          if (typeof value !== "number") {
+            Logger.Default.error(`[NT4Client] unexpected non-numeric value in RTT frame, message ignored`);
+            continue;
+          }
+
+          const clientTime_μs = this.getClientTimestamp_μs();
+          const latency_μs = (clientTime_μs - value) / 2.0; // network latency is estimated as half of RTT
+
+          // if the RTT is less than that from previous measurements, the client shall use
+          // the timestamp in the message plus ½ the RTT as the server time equivalent to
+          // the current local time
+          if (this.networkLatency_μs == null || latency_μs < this.networkLatency_μs) {
+            const clockSynchronized = this.serverTimeOffset_μs == null;
+
+            // server timestamp is in microseconds
+            this.serverTimeOffset_μs = Math.round(timestamp + latency_μs - clientTime_μs);
+
+            if (clockSynchronized) {
+              this.onClockSynchronized();
+            }
+          }
+
+          this.networkLatency_μs = latency_μs;
+
+          // update pong timestamp (used for checking timeouts)
+          this.pongTimestamp_μs = clientTime_μs;
+        } else if (topicId > 0) {
+          const topic = this.announcedTopicsIndex.get(topicId);
+          if (topic == null) {
+            Logger.Default.error(`[NT4Client] unexpected topic identifier ${topicId}, message ignored`);
+            continue;
+          } else if (this.onDataReceived) {
+            // update locally retained value on topics published by the client
+            this.publishedTopics.get(topic.name)?.updateRetainedValue(value, timestamp);
+            this.onDataReceived(topic, value, timestamp);
+          }
+        } else {
+          Logger.Default.error(`[NT4Client] invalid topic identifier ${topicId}, message ignored`);
+          continue;
+        }
+      }
+    }
+  }
+
+  /** Handles general data frame received. */
+  private onChannelMessage = (ev: MessageEvent) => {
+    this.processDataFrame(ev.data);
+  };
+
+  /** Handles RTT data frame received. */
+  private onChannelMessageRTT = (ev: MessageEvent) => {
+    if (typeof ev.data === "string") {
+      Logger.Default.debug(`[NT4Client] unexpected text data frame on RTT channel, frame ignored`);
+      return;
+    }
+
+    this.processDataFrame(ev.data);
+  };
+
+  /** Handles channel closing for whatever reason. */
+  private onChannelClose = (ev: CloseEvent) => {
+    Logger.Default.debug(`[NT4Client] channel closed`, ev);
+
+    this.cleanup();
+    this.connectWithRetry();
+  };
+
+  /** Returns current timestamp in microseconds. This is NOT wall clock time. */
+  private getClientTimestamp_μs() {
+    // monotonically increasing, microsecond precision
+    return Math.round(performance.now() * 1000);
+  }
+
+  /** Sends data frame to publish the topic. */
+  private publishCore(topic: NT4Topic) {
+    this.dataChannel.sendText({
+      method: "publish",
+      params: {
+        pubuid: topic.uid,
+        name: topic.name,
+        type: topic.type,
+        properties: topic.properties,
+      },
+    });
+  }
+
+  /** Sends data frame to unpublish the topic. */
+  private unpublishCore(topic: NT4Topic) {
+    this.dataChannel.sendText({
+      method: "unpublish",
+      params: {
+        pubuid: topic.uid,
+      },
+    });
+  }
+
+  /** Sends data frame to set topic properties. */
+  private setPropertiesCore(name: string, properties: TopicProperties) {
+    this.dataChannel.sendText({
+      method: "setproperties",
+      params: {
+        name: name,
+        update: properties,
+      },
+    });
+  }
+
+  /** Sends data frame to subscribe the subscription. */
+  private subscribeCore(subscription: NT4Subscription) {
+    this.dataChannel.sendText({
+      method: "subscribe",
+      params: {
+        subuid: subscription.uid,
+        topics: Array.from(subscription.topics),
+        options: subscription.options,
+      },
+    });
+  }
+
+  /** Sends data frame to unsubscribe the subscription. */
+  private unsubscribeCore(subscription: NT4Subscription) {
+    this.dataChannel.sendText({
+      method: "unsubscribe",
+      params: {
+        subuid: subscription.uid,
+      },
+    });
+  }
+
+  /** Sends data frame to update topic value. */
+  private sendValueCore(topic: NT4Topic, value: unknown, timestamp: number) {
+    const frame = this.encoder.encode([topic.uid, timestamp, topic.typeCode, value]);
+    this.dataChannel.sendBinary(frame);
+  }
+
+  /**
+   * Sends RTT measurement binary frame.
+   * Uses RTT channel if available, falls back to data channel in NT4.0.
+   */
+  private sendRTT() {
+    // https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#timestamps
+    // The topic ID of -1 is reserved for timestamp communication.
+    // Clients shall periodically (e.g. every few seconds) send, in a manner that
+    // minimizes transmission delays, a MessagePack message with ID of -1, a timestamp of 0,
+    // and an implementation-selected type and data value (typically int or float 64)
+    // containing its (the client’s) current local time
+    const timestamp = this.getClientTimestamp_μs();
+    const frame = this.encoder.encode([-1, 0, DataTypeCodes.double, timestamp]);
+    (this.rttChannel ?? this.dataChannel).sendBinary(frame);
+  }
+
+  /**
+   * Determines whether connection times out if no message has been received
+   * within the timeout interval since the last pong.
+   */
+  private async checkTimeout() {
+    if (!this.connectionEstablished || this.pongTimestamp_μs === 0) {
+      return;
+    }
+
+    const delta_μs = this.getClientTimestamp_μs() - this.pongTimestamp_μs;
+    if (delta_μs > this.pingTimeout_ms * 1000) {
+      Logger.Default.debug(
+        `[NT4Client] no data received in the last ${(delta_μs / 1000).toFixed(0)}ms, connection timed out`
+      );
+
+      await this.dataChannel.close(4001, "timeout");
+      this.cleanup();
+      this.connectWithRetry();
+    }
+  }
+
+  /** Generates random UID. */
+  private generateUID() {
+    return Math.floor(Math.random() * 0x7fffffff);
+  }
+
+  /** Generates random safe UID avoiding possible clashes. */
+  private generateSafeUID(has: (id: number) => boolean) {
+    let uid: number;
+    for (uid = this.generateUID(); has(uid); uid = this.generateUID());
+    return uid;
+  }
+
+  /** Determines whether published topic with the specified identifier exists. */
+  private readonly hasPublishedTopicWithId = (id: number) => some(this.publishedTopics, (_) => _.uid === id);
+
+  /** Determines whether subscription with the specified identifier exists. */
+  private readonly hasSubscriptionWithId = (id: number) => this.subscriptions.has(id);
+
+  /**
+   * Constructs an instance of NT4Client without initiating a connection.
+   *
+   * @param serverAddress NT4 server network address
+   * @param clientId this client identifier (cannot contain '@')
+   * @param options options
+   */
+  constructor(serverAddress: string, clientId: string, options: NT4ClientOptions) {
+    // https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#websockets-protocol-configuration
+    // ...
+    // The client name does not need to be unique; multiple connections to the same name are allowed;
+    // the server shall ensure the name is unique (for the purposes of meta-topics) by appending a '@'
+    // and a unique number (if necessary). To support this, the name provided by the client should not
+    // contain an embedded '@'. Clients should provide a way to specify the resource name (in particular,
+    // the client name portion).
+    if (clientId.includes("@")) {
+      throw new Error("Client identifier must not contain '@' character");
+    }
+
+    this.serverAddress = serverAddress;
+    this.port = options.secure ? NetworkSpecs.portSecure : NetworkSpecs.portUnsecure;
+    this.clientId = clientId;
+    this.onConnect = options.onConnect;
+    this.onDisconnect = options.onDisconnect;
+    this.onTopicAnnounced = options.onTopicAnnounced;
+    this.onTopicRemoved = options.onTopicRemoved;
+    this.onTopicUpdated = options.onTopicUpdated;
+    this.onDataReceived = options.onDataReceived;
+    this.retryPolicy = options.retryPolicy ?? NT4Client.defaultRetryPolicy;
+    this.pingTimeoutOverride_ms = options.pingTimeoutMilliseconds;
+
+    // data messages channel
+    this.dataChannel = new NT4WebSocketAsync(this.serverAddress, this.port, this.clientId, {
+      secure: options.secure,
+      onMessage: this.onChannelMessage,
+      onClose: this.onChannelClose,
+    });
+
+    // RTT messages channel (only used in NT4.1)
+    this.rttChannel = new NT4WebSocketAsync(this.serverAddress, this.port, this.clientId, {
+      rtt: true,
+      secure: options.secure,
+      onMessage: this.onChannelMessageRTT,
+    });
+  }
+
+  /**
+   * Returns NT4 server network address the client is using.
+   */
+  public readonly serverAddress: string;
+
+  /**
+   * Returns current connection state.
+   */
+  public get state() {
+    return this.connectionState;
+  }
+
+  /**
+   * Returns current network latency in microseconds if known.
+   */
+  public get networkLatencyMicroseconds() {
+    return this.networkLatency_μs;
+  }
+
+  /**
+   * Returns server time in microseconds that is current or
+   * based on the specified client (local) time.
+   *
+   * Returns `null` if the server time offset is not established.
+   */
+  public serverTimeMicroseconds(clientTimeMicroseconds?: number) {
+    return this.serverTimeOffset_μs != null
+      ? Math.round(
+          (clientTimeMicroseconds != null ? clientTimeMicroseconds : this.getClientTimestamp_μs()) +
+            this.serverTimeOffset_μs
+        )
+      : null;
+  }
+
+  /**
+   * Initiates the connection.
+   * Once established the connection will be automatically kept alive by reconnecting.
+   */
+  public connect() {
+    if (this.connectionInitiated) {
+      return;
+    }
+
+    Logger.Default.debug(`[NT4Client] connection initiated`);
+    this.connectionInitiated = true;
+    this.connectWithRetry();
+  }
+
+  /**
+   * Terminates the connection.
+   * The client can be reconnected manually by calling {@link connect} again.
+   */
+  public disconnect() {
+    if (!this.connectionInitiated) {
+      return;
+    }
+
+    Logger.Default.debug(`[NT4Client] connection cancelled`);
+    this.connectionInitiated = false;
+    this.dataChannel.close();
+    this.rttChannel.close();
+  }
+
+  /**
+   * Creates a new subscription.
+   *
+   * The subscription can be created regardless of connectivity state.
+   * All client subscriptions are automatically restored once connection
+   * has been established. This is also true for reconnects following
+   * loss of connectivity or deliberate disconnects.
+   *
+   * Caller can {@link unsubscribe} by passing the return value of this call or
+   * invoke {@link unsubscribeAll} to remove all existing client subscriptions.
+   *
+   * @param topics topics or prefixes to include in the subscription
+   * @param options subscription options
+   * @returns A subscription instance
+   */
+  public subscribe(topics: Iterable<string>, options: SubscriptionOptions) {
+    const uid = this.generateSafeUID(this.hasSubscriptionWithId);
+    const subscription = new NT4Subscription(uid, topics, options);
+    this.subscriptions.set(subscription.uid, subscription);
+
+    if (this.connectionEstablished) {
+      this.subscribeCore(subscription);
+    }
+
+    return subscription;
+  }
+
+  /**
+   * Unsubscribes an existing subscription.
+   *
+   * @param arg subscription or subscription identifier
+   * @returns `true` if the subscription was successfully unsubscribed, `false` if the subscription was not found
+   */
+  public unsubscribe(arg: NT4Subscription | number) {
+    const subscription = typeof arg === "number" ? this.subscriptions.get(arg) : arg;
+    if (!subscription) {
+      return false;
+    }
+
+    this.subscriptions.delete(subscription.uid);
+    if (this.connectionEstablished) {
+      this.unsubscribeCore(subscription);
+    }
+
+    return true;
+  }
+
+  /**
+   * Unsubscribes all existing subscriptions.
+   */
+  public unsubscribeAll() {
+    for (const subscription of this.subscriptions.values()) {
+      this.unsubscribe(subscription);
+    }
+  }
+
+  /**
+   * Publishes a topic with the specified name and type.
+   *
+   * This method registers this client as a publisher for the topic.
+   * It should be called before {@link setValue} or {@link setValueAt}
+   * can be used.
+   *
+   * Publishing a topic on a disconnected client is allowed.
+   * Client will automatically register such publishers once the connection
+   * has been established and send default or retained value as appropriate.
+   *
+   * @param topic topic name
+   * @param type data type
+   * @param properties properties
+   */
+  public publishTopic(topic: string, type: DataType | string, properties?: TopicProperties) {
+    let publishedTopic = this.publishedTopics.get(topic);
+    if (publishedTopic) {
+      return publishedTopic;
+    }
+
+    const uid = this.generateSafeUID(this.hasPublishedTopicWithId);
+    publishedTopic = new NT4Topic(uid, topic, type, properties, uid);
+    this.publishedTopics.set(publishedTopic.name, publishedTopic);
+
+    if (this.connectionEstablished) {
+      this.publishCore(publishedTopic);
+    }
+
+    return publishedTopic;
+  }
+
+  /**
+   * Un-publishes previously published topic.
+   *
+   * @param topic topic name
+   * @returns `true` if the topic was successfully unpublished, `false` if the topic was not published
+   */
+  public unpublishTopic(topic: string) {
+    const publishedTopic = this.publishedTopics.get(topic);
+    if (!publishedTopic) {
+      return false;
+    }
+
+    this.publishedTopics.delete(publishedTopic.name);
+    if (this.connectionEstablished) {
+      this.unpublishCore(publishedTopic);
+    }
+
+    return true;
+  }
+
+  /**
+   * Determines whether client already publishes the topic.
+   *
+   * @param topic topic name
+   */
+  public isTopicPublished(topic: string) {
+    return this.publishedTopics.has(topic);
+  }
+
+  /**
+   * Sets properties for the specified topic.
+   *
+   * @param topic topic name
+   * @param properties new properties
+   */
+  public setTopicProperties(topic: string, properties: TopicProperties) {
+    const publishedTopic = this.publishedTopics.get(topic);
+    if (publishedTopic) {
+      publishedTopic.mergeProperties(properties);
+    }
+
+    const announcedTopic = this.announcedTopics.get(topic);
+    if (announcedTopic) {
+      announcedTopic.mergeProperties(properties);
+    }
+
+    if (this.connectionEstablished) {
+      this.setPropertiesCore(topic, properties);
+    }
+  }
+
+  /**
+   * Sets persistent flag for the topic.
+   *
+   * @param topic topic name
+   * @param value value to set
+   */
+  public setTopicPersistent(topic: string, value: boolean) {
+    this.setTopicProperties(topic, { persistent: value });
+  }
+
+  /**
+   * Sets retained flag for the topic.
+   *
+   * @param topic topic name
+   * @param value value to set
+   */
+  public setTopicRetained(topic: string, value: boolean) {
+    this.setTopicProperties(topic, { retained: value });
+  }
+
+  /**
+   * Sends a value to the published topic using the current time.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   */
+  public setValue(topic: string, value: unknown) {
+    this.setValueAt(topic, value, this.serverTimeMicroseconds() ?? 1);
+  }
+
+  /**
+   * Sends a default ("weak") value to the published topic.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   */
+  public setDefaultValue(topic: string, value: unknown) {
+    this.setValueAt(topic, value, 0);
+  }
+
+  /**
+   * Sends a value to the published topic using the specified timestamp.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   * @param timestamp timestamp
+   */
+  public setValueAt(topic: string, value: unknown, timestamp: number) {
+    const publishedTopic = this.publishedTopics.get(topic);
+    if (!publishedTopic) {
+      throw new Error("Topic must be published first");
+    }
+
+    // timestamps in messages always use the server time base,
+    // if the offset has not been established, the client retains
+    // the last value and will send it once connection is restored
+    publishedTopic.updateRetainedValue(value, timestamp);
+
+    // update locally for announced topics
+    if (this.onDataReceived) {
+      const announcedTopic = this.announcedTopics.get(topic);
+      if (announcedTopic) {
+        this.onDataReceived(announcedTopic, value, timestamp);
+      }
+    }
+
+    if (this.connectionEstablished && this.serverTimeOffset_μs != null) {
+      this.sendValueCore(publishedTopic, value, timestamp);
+    }
+  }
+
+  /**
+   * Returns current ping timeout.
+   *
+   * @returns A value in milliseconds or 0 if the timeout has not been set yet.
+   */
+  public get pingTimeoutMilliseconds() {
+    return this.pingTimeout_ms;
+  }
+
+  /**
+   * Sets ping timeout.
+   *
+   * @param value Timeout in milliseconds or `undefined` to use default protocol timeout value.
+   */
+  public setPingTimeoutMilliseconds(value: number | undefined) {
+    Logger.Default.debug(
+      value != null
+        ? `[NT4Client] ping timeout is set to ${value.toFixed(0)}ms`
+        : `[NT4Client] ping timeout is reset to protocol-based default`
+    );
+
+    this.pingTimeoutOverride_ms = value;
+
+    // update actual timeout value
+    if (value != null) {
+      this.pingTimeout_ms = value;
+    } else {
+      this.pingTimeout_ms =
+        this.dataChannel.protocol === NetworkSpecs.protocol41 ? NetworkSpecs.pingTimeout41 : NetworkSpecs.pingPeriod40;
+    }
+  }
+}