@flux-control/effect-modbus-rs 0.5.0 → 0.6.0

package/README.md

@@ -711,6 +711,32 @@ Effect.gen(function* () {
 });
 ```
 
+### Connect timeout
+
+The `modbus-rs` bindings do not limit the time of a connect. A TCP connect to a host that does not answer waits until the operating system stops it. On Linux with default settings, this takes about 2 minutes. During that time, every operation joins the same pending connect.
+
+Set `connectTimeout` to limit how long each operation waits for an open or a reconnect:
+
+```ts
+TcpTransportService.make({
+  host: '192.0.2.1',
+  port: 502,
+  connectTimeout: '3 seconds', // limit for each wait on an open or reconnect
+  reconnect: {},
+});
+```
+
+The limit applies to each operation that waits for an open or reconnect. When it expires, that operation fails with `ModbusTimeoutError`.
+
+The native connect cannot be cancelled, so it continues after the timeout:
+
+- Later operations wait for the same native connect, each for at most the limit. A transport never has more than one pending native connect.
+- When the native connect succeeds later, the transport uses it. A late reconnect that succeeds after the supervisor published `Down` publishes `Connected` at once.
+- When the native connect fails, the next operation starts a new connect.
+- A supervised reconnect attempt that times out is retried by the reconnect policy by default. When the attempts are exhausted, the transport publishes `Down`.
+
+The option applies to every transport. It is unbounded by default. `requestTimeoutMs` limits each request, but it does not limit the connect.
+
 ### Retrying a transaction
 
 `retryModbus(policy)` remains exported for the one case the transport cannot express: driving a **compound** operation as a unit, where retrying individual frames would be wrong.

package/dist/index.js

@@ -1250,7 +1250,7 @@ var createMockTransport = (devices) => {
 };
 
 // src/shared-transport.ts
-import { Deferred as Deferred4, Effect as Effect8, Exit as Exit4, Option, Ref, Scope as Scope3, SubscriptionRef as SubscriptionRef4 } from "effect";
+import { Deferred as Deferred4, Duration as Duration6, Effect as Effect8, Exit as Exit4, Option, Ref, Scope as Scope3, SubscriptionRef as SubscriptionRef4 } from "effect";
 var makeInFlight = () => Ref.make(Option.none());
 var singleFlight = (inFlight, work) => Effect8.uninterruptibleMask((restore) => Effect8.gen(function* () {
   const fresh = yield* Deferred4.make();
@@ -1292,9 +1292,11 @@ var loadTransportConstructor = async (transportKey, moduleSpecifier) => {
 function createTransportScoped(transportKey, openMethod, serviceName, config) {
   return Effect8.fnUntraced(function* (options) {
     const { retry: transportRetry, reconnect: reconnectOptions } = options;
+    const connectTimeout = options.connectTimeout === undefined ? undefined : Duration6.fromInputUnsafe(options.connectTimeout);
     const openOptions = { ...options };
     Reflect.deleteProperty(openOptions, "retry");
     Reflect.deleteProperty(openOptions, "reconnect");
+    Reflect.deleteProperty(openOptions, "connectTimeout");
     const TC = yield* Effect8.promise(() => loadTransportConstructor(transportKey, config?.moduleSpecifier ?? "modbus-rs"));
     let transport = null;
     const opening = yield* makeInFlight();
@@ -1310,6 +1312,15 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
       message: "Transport has been closed"
     });
     const closeOrphan = (t) => Effect8.forkDetach(Effect8.ignore(Effect8.tryPromise(() => t.close())));
+    const limitConnect = (wait) => {
+      if (connectTimeout === undefined)
+        return wait;
+      const message = `${serviceName}: connect did not complete within ${Duration6.format(connectTimeout)}`;
+      return Effect8.timeoutOrElse(wait, {
+        duration: connectTimeout,
+        orElse: () => Effect8.fail(new ModbusTimeoutError({ cause: new Error(message), message }))
+      });
+    };
     const openTransport = Effect8.tryPromise({
       try: () => openMethod(TC, openOptions),
       catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
@@ -1321,7 +1332,7 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
         return yield* transportClosed();
       if (transport)
         return transport;
-      const t = yield* singleFlight(opening, openTransport);
+      const t = yield* limitConnect(singleFlight(opening, openTransport));
       if (closed)
         return yield* transportClosed();
       return t;
@@ -1340,14 +1351,15 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
     });
     yield* Effect8.addFinalizer(() => Effect8.orDie(closeTransport));
     const notConnectedMsg = "Transport is not connected. Call withClient() first.";
+    const reconnectTransport = (t) => limitConnect(singleFlight(reconnecting, Effect8.tryPromise({
+      try: () => t.reconnect(),
+      catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
+    }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : SubscriptionRef4.update(connectionState, (current) => ConnectionState.$is("Down")(current) ? ConnectionState.Connected() : current)))));
     const reconnectOnce = Effect8.suspend(() => {
       const t = transport;
       if (closed || !t)
         return transportClosed();
-      return singleFlight(reconnecting, Effect8.tryPromise({
-        try: () => t.reconnect(),
-        catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
-      }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : Effect8.void)));
+      return reconnectTransport(t);
     });
     const report = (error) => {
       if (closed || !resolvedReconnect.triggers(error))
@@ -1424,10 +1436,7 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
           yield* ensureOpen();
           return;
         }
-        yield* singleFlight(reconnecting, Effect8.tryPromise({
-          try: () => t.reconnect(),
-          catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
-        }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : Effect8.void)));
+        yield* reconnectTransport(t);
         if (closed)
           return yield* transportClosed();
         yield* SubscriptionRef4.set(connectionState, ConnectionState.Connected());

package/dist/src/errors.d.ts

@@ -30,6 +30,9 @@ declare const ModbusTimeoutError_base: new <A extends Record<string, any> = {}>(
  * with {@link RtuTransportOptions.requestTimeoutMs | requestTimeoutMs} /
  * {@link RtuTransportOptions.responseTimeoutMs | responseTimeoutMs}.
  *
+ * The transport also raises this error locally when an operation waits for an
+ * open or reconnect longer than the `connectTimeout` transport option.
+ *
  * @see ModbusErrorCode.TIMEOUT — `modbus-rs` error code that triggers this error.
  */
 export declare class ModbusTimeoutError extends ModbusTimeoutError_base<{

package/dist/src/shared-transport.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Scope, SubscriptionRef } from 'effect';
+import { Duration, Effect, Scope, SubscriptionRef } from 'effect';
 import type { AsyncAsciiTransport, AsyncRtuTransport, AsyncTcpTransport } from 'modbus-rs';
 import type { WasmAsciiTransport, WasmRtuTransport, WasmWsTransport } from 'modbus-rs/web';
 import { type BatchingClientOptions, type BatchingModbusClient } from './batching-client';
@@ -24,6 +24,24 @@ export interface TransportResilienceOptions {
      * enables the circuit breaker that keeps callers off a dead bus.
      */
     readonly reconnect?: ReconnectOptions;
+    /**
+     * Time limit for each operation that waits for an open or reconnect of the
+     * underlying transport.
+     *
+     * The `modbus-rs` bindings do not limit the connect time. A TCP connect to a
+     * host that does not answer waits until the operating system stops it, which
+     * takes about 2 minutes on Linux with default settings.
+     *
+     * The limit applies to each caller that waits for an open or reconnect.
+     * When it expires, that caller fails with {@link ModbusTimeoutError}.
+     *
+     * The native connect cannot be cancelled, so it continues. Later callers wait
+     * for the same native connect, each for at most this limit, so one transport
+     * has at most one pending native connect. When the native connect succeeds
+     * later, the transport uses it. When it fails, the next caller starts a new
+     * connect. Unbounded by default.
+     */
+    readonly connectTimeout?: Duration.Input;
 }
 /**
  * The `modbus-rs` transport-level retry knobs this package deliberately does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flux-control/effect-modbus-rs",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
   "license": "GPL-3.0",
   "repository": {