@homaiohq/napi-quickfix 0.0.0-stage → 0.2.0

package/cpp/session_wrap.cpp

@@ -0,0 +1,438 @@
+#include "session_wrap.h"
+
+#include <cmath>
+#include <ctime>
+#include <limits>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "errors.h"
+#include "quickfix/Exceptions.h"
+#include "quickfix/FieldTypes.h"
+#include "session_id_wrap.h"
+
+namespace napi_quickfix {
+
+Napi::FunctionReference SessionWrap::constructor_;
+
+Napi::Object SessionWrap::Init(Napi::Env env, Napi::Object exports) {
+  Napi::Function func = DefineClass(
+      env, "Session",
+      {
+          InstanceMethod("getSessionID", &SessionWrap::GetSessionID),
+
+          InstanceMethod("isLoggedOn", &SessionWrap::IsLoggedOn),
+          InstanceMethod("isEnabled", &SessionWrap::IsEnabled),
+          InstanceMethod("sentLogon", &SessionWrap::SentLogon),
+          InstanceMethod("sentLogout", &SessionWrap::SentLogout),
+          InstanceMethod("receivedLogon", &SessionWrap::ReceivedLogon),
+          InstanceMethod("isInitiator", &SessionWrap::IsInitiator),
+          InstanceMethod("isAcceptor", &SessionWrap::IsAcceptor),
+          InstanceMethod("isSessionTime", &SessionWrap::IsSessionTime),
+          InstanceMethod("isLogonTime", &SessionWrap::IsLogonTime),
+
+          InstanceMethod("getExpectedSenderNum",
+                         &SessionWrap::GetExpectedSenderNum),
+          InstanceMethod("getExpectedTargetNum",
+                         &SessionWrap::GetExpectedTargetNum),
+          InstanceMethod("setNextSenderMsgSeqNum",
+                         &SessionWrap::SetNextSenderMsgSeqNum),
+          InstanceMethod("setNextTargetMsgSeqNum",
+                         &SessionWrap::SetNextTargetMsgSeqNum),
+
+          InstanceMethod("getResetOnLogon", &SessionWrap::GetResetOnLogon),
+          InstanceMethod("setResetOnLogon", &SessionWrap::SetResetOnLogon),
+          InstanceMethod("getResetOnLogout", &SessionWrap::GetResetOnLogout),
+          InstanceMethod("setResetOnLogout", &SessionWrap::SetResetOnLogout),
+          InstanceMethod("getResetOnDisconnect",
+                         &SessionWrap::GetResetOnDisconnect),
+          InstanceMethod("setResetOnDisconnect",
+                         &SessionWrap::SetResetOnDisconnect),
+          InstanceMethod("getRefreshOnLogon", &SessionWrap::GetRefreshOnLogon),
+          InstanceMethod("setRefreshOnLogon", &SessionWrap::SetRefreshOnLogon),
+          InstanceMethod("getCheckCompId", &SessionWrap::GetCheckCompId),
+          InstanceMethod("setCheckCompId", &SessionWrap::SetCheckCompId),
+          InstanceMethod("getCheckLatency", &SessionWrap::GetCheckLatency),
+          InstanceMethod("setCheckLatency", &SessionWrap::SetCheckLatency),
+          InstanceMethod("getPersistMessages",
+                         &SessionWrap::GetPersistMessages),
+          InstanceMethod("setPersistMessages",
+                         &SessionWrap::SetPersistMessages),
+          InstanceMethod("getSendRedundantResendRequests",
+                         &SessionWrap::GetSendRedundantResendRequests),
+          InstanceMethod("setSendRedundantResendRequests",
+                         &SessionWrap::SetSendRedundantResendRequests),
+          InstanceMethod("getValidateLengthAndChecksum",
+                         &SessionWrap::GetValidateLengthAndChecksum),
+          InstanceMethod("setValidateLengthAndChecksum",
+                         &SessionWrap::SetValidateLengthAndChecksum),
+          InstanceMethod("getSendNextExpectedMsgSeqNum",
+                         &SessionWrap::GetSendNextExpectedMsgSeqNum),
+          InstanceMethod("setSendNextExpectedMsgSeqNum",
+                         &SessionWrap::SetSendNextExpectedMsgSeqNum),
+          InstanceMethod("getIsNonStopSession",
+                         &SessionWrap::GetIsNonStopSession),
+          InstanceMethod("setIsNonStopSession",
+                         &SessionWrap::SetIsNonStopSession),
+          InstanceMethod("getLogonTimeout", &SessionWrap::GetLogonTimeout),
+          InstanceMethod("setLogonTimeout", &SessionWrap::SetLogonTimeout),
+          InstanceMethod("getLogoutTimeout", &SessionWrap::GetLogoutTimeout),
+          InstanceMethod("setLogoutTimeout", &SessionWrap::SetLogoutTimeout),
+          InstanceMethod("getMaxLatency", &SessionWrap::GetMaxLatency),
+          InstanceMethod("setMaxLatency", &SessionWrap::SetMaxLatency),
+          InstanceMethod("getTimestampPrecision",
+                         &SessionWrap::GetTimestampPrecision),
+          InstanceMethod("setTimestampPrecision",
+                         &SessionWrap::SetTimestampPrecision),
+
+          InstanceMethod("logon", &SessionWrap::Logon),
+          InstanceMethod("logout", &SessionWrap::Logout),
+          InstanceMethod("refresh", &SessionWrap::Refresh),
+      });
+
+  constructor_ = Napi::Persistent(func);
+  constructor_.SuppressDestruct();
+
+  exports.Set("SessionWrap", func);
+  return exports;
+}
+
+Napi::Object SessionWrap::NewInstance(Napi::Env env, const FIX::SessionID& id,
+                                      std::shared_ptr<SessionOpGate> gate) {
+  Napi::Object obj = constructor_.New({SessionIDWrap::NewInstance(env, id)});
+  Unwrap(obj)->gate_ = std::move(gate);
+  return obj;
+}
+
+SessionWrap::SessionWrap(const Napi::CallbackInfo& info)
+    : Napi::ObjectWrap<SessionWrap>(info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1) {
+    throw Napi::TypeError::New(
+        env,
+        "Session cannot be constructed directly; use lookupSession() or "
+        "engine.getSession()");
+  }
+  // Copy by value: the wrap must outlive any SessionID JS object.
+  id_ = SessionIDWrap::UnwrapArg(env, info[0], "sessionID")->SessionID();
+}
+
+// Engines are created and destroyed on the JS thread only, and so is this
+// call, so the owner check and the lookup cannot interleave with an engine
+// stop. During a graceful stop() the gate stays registered until the engine is
+// destroyed (Freeze() -> Unregister() -> delete, all before stop() settles), so
+// a 'logout' listener fired by the stop still resolves the session.
+FIX::Session& SessionWrap::Resolve() {
+  if (!gate_ || SessionOpGate::Lookup(id_) != gate_) {
+    throw FIX::SessionNotFound(id_.toString());
+  }
+  FIX::Session* session = FIX::Session::lookupSession(id_);
+  if (session == nullptr) {
+    throw FIX::SessionNotFound(id_.toString());
+  }
+  return *session;
+}
+
+Napi::Value SessionWrap::GetSessionID(const Napi::CallbackInfo& info) {
+  return SessionIDWrap::NewInstance(info.Env(), id_);
+}
+
+// --- generic helpers ---------------------------------------------------------
+
+template <typename Fn>
+Napi::Value SessionWrap::BoolGet(const Napi::CallbackInfo& info, Fn fn) {
+  Napi::Env env = info.Env();
+  NQ_TRY(env) {
+    return Napi::Boolean::New(env, (Resolve().*fn)());
+  } NQ_CATCH(env)
+}
+
+template <typename Fn>
+Napi::Value SessionWrap::IntGet(const Napi::CallbackInfo& info, Fn fn) {
+  Napi::Env env = info.Env();
+  NQ_TRY(env) {
+    return Napi::Number::New(env, static_cast<double>((Resolve().*fn)()));
+  } NQ_CATCH(env)
+}
+
+template <typename Fn>
+Napi::Value SessionWrap::BoolSet(const Napi::CallbackInfo& info, Fn fn,
+                                 const char* name) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsBoolean()) {
+    throw Napi::TypeError::New(env, std::string(name) + "(value: boolean)");
+  }
+  const bool value = info[0].As<Napi::Boolean>().Value();
+  NQ_TRY(env) {
+    (Resolve().*fn)(value);
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+// The FIX::Session setters take a plain `int`; a double outside its range is
+// undefined behaviour to cast (and on x86-64 lands on INT_MIN, which would e.g.
+// make a MaxLatency reject every inbound message). Bound it here and report
+// a RangeError, matching SeqNumSet / SetTimestampPrecision.
+template <typename Fn>
+Napi::Value SessionWrap::IntSet(const Napi::CallbackInfo& info, Fn fn,
+                                const char* name) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsNumber()) {
+    throw Napi::TypeError::New(env, std::string(name) + "(value: number)");
+  }
+  const double raw = info[0].As<Napi::Number>().DoubleValue();
+  constexpr double kIntMin = static_cast<double>(std::numeric_limits<int>::min());
+  constexpr double kIntMax = static_cast<double>(std::numeric_limits<int>::max());
+  if (!std::isfinite(raw) || std::floor(raw) != raw || raw < kIntMin ||
+      raw > kIntMax) {
+    throw Napi::RangeError::New(
+        env, std::string(name) + ": value must be an integer in the int32 range");
+  }
+  NQ_TRY(env) {
+    (Resolve().*fn)(static_cast<int>(raw));
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+// isSessionTime(nowMs?) / isLogonTime(nowMs?): `nowMs` is an epoch-millisecond
+// number (Date.getTime()); omitted => the engine's current UTC clock.
+Napi::Value SessionWrap::TimeCheck(const Napi::CallbackInfo& info,
+                                   bool logonTime) {
+  Napi::Env env = info.Env();
+  bool hasNow = info.Length() >= 1 && !info[0].IsUndefined();
+  double nowMs = 0;
+  if (hasNow) {
+    if (!info[0].IsNumber()) {
+      throw Napi::TypeError::New(
+          env, logonTime ? "isLogonTime(nowMs?: number)"
+                         : "isSessionTime(nowMs?: number)");
+    }
+    nowMs = info[0].As<Napi::Number>().DoubleValue();
+    // Bound to the range a JS Date can hold (+/- 100M days around the epoch)
+    // before the floating-to-integer cast below: converting a finite double
+    // that does not fit in time_t is undefined behaviour, not a saturation.
+    constexpr double kMaxDateMs = 8.64e15;
+    if (!std::isfinite(nowMs) || std::fabs(nowMs) > kMaxDateMs) {
+      throw Napi::RangeError::New(
+          env, "nowMs must be an epoch-millisecond number in the Date range");
+    }
+  }
+  NQ_TRY(env) {
+    FIX::Session& session = Resolve();
+    FIX::UtcTimeStamp now = FIX::UtcTimeStamp::now();
+    if (hasNow) {
+      const double secs = std::floor(nowMs / 1000.0);
+      const int millis = static_cast<int>(nowMs - secs * 1000.0);
+      now = FIX::UtcTimeStamp(static_cast<time_t>(secs), millis);
+    }
+    return Napi::Boolean::New(env, logonTime ? session.isLogonTime(now)
+                                             : session.isSessionTime(now));
+  } NQ_CATCH(env)
+}
+
+// Sequence numbers are FIX::SEQNUM (uint64_t). JS numbers are exact up to
+// 2^53, which is far beyond any practical MsgSeqNum; reject anything that is
+// not a positive safe integer. MsgSeqNum (tag 34) is 1-based: QuickFIX's own
+// SessionState::reset() and MemoryStore start at 1, and a peer answers 34=0
+// with a Logout ("MsgSeqNum too low").
+Napi::Value SessionWrap::SeqNumSet(const Napi::CallbackInfo& info, bool sender,
+                                   const char* name) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsNumber()) {
+    throw Napi::TypeError::New(env, std::string(name) + "(seqNum: number)");
+  }
+  const double raw = info[0].As<Napi::Number>().DoubleValue();
+  constexpr double kMaxSafe = 9007199254740991.0;  // Number.MAX_SAFE_INTEGER
+  if (!std::isfinite(raw) || std::floor(raw) != raw || raw < 1 ||
+      raw > kMaxSafe) {
+    throw Napi::RangeError::New(
+        env, std::string(name) + ": seqNum must be a positive safe integer");
+  }
+  const FIX::SEQNUM num = static_cast<FIX::SEQNUM>(raw);
+  NQ_TRY(env) {
+    // These touch the MessageStore (may throw IOException) but take only the
+    // SessionState mutex, which QuickFIX never holds across a callback -- that
+    // is what makes them safe to run here. It also means they are NOT
+    // serialised against the engine: Session::sendRaw holds m_mutex across
+    // fill() (reads the next sender num into the header), toApp/toAdmin and
+    // persist() (incrNextSenderMsgSeqNum from the store), and Session::next()
+    // likewise across the target-num verification, fromApp/fromAdmin and
+    // incrNextTargetMsgSeqNum. A setter landing inside that window -- from a
+    // handler, or while a sendToTarget() / heartbeat is in flight on this
+    // session -- is overwritten by the increment that follows, and the wire
+    // is left one off from the peer. The setters are meant for a quiescent
+    // session (before start(), from a 'logout' event, or when the caller
+    // knows nothing is in flight); documented on the JS API, not fixable here
+    // (m_mutex is private and must not be taken from the JS thread anyway).
+    if (sender) {
+      Resolve().setNextSenderMsgSeqNum(num);
+    } else {
+      Resolve().setNextTargetMsgSeqNum(num);
+    }
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+// --- state getters -----------------------------------------------------------
+
+Napi::Value SessionWrap::IsLoggedOn(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::isLoggedOn);
+}
+Napi::Value SessionWrap::IsEnabled(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::isEnabled);
+}
+Napi::Value SessionWrap::SentLogon(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::sentLogon);
+}
+Napi::Value SessionWrap::SentLogout(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::sentLogout);
+}
+Napi::Value SessionWrap::ReceivedLogon(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::receivedLogon);
+}
+Napi::Value SessionWrap::IsInitiator(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::isInitiator);
+}
+Napi::Value SessionWrap::IsAcceptor(const Napi::CallbackInfo& info) {
+  return BoolGet(info, &FIX::Session::isAcceptor);
+}
+Napi::Value SessionWrap::IsSessionTime(const Napi::CallbackInfo& info) {
+  return TimeCheck(info, /*logonTime=*/false);
+}
+Napi::Value SessionWrap::IsLogonTime(const Napi::CallbackInfo& info) {
+  return TimeCheck(info, /*logonTime=*/true);
+}
+
+// --- sequence numbers --------------------------------------------------------
+
+Napi::Value SessionWrap::GetExpectedSenderNum(const Napi::CallbackInfo& info) {
+  return IntGet(info, &FIX::Session::getExpectedSenderNum);
+}
+Napi::Value SessionWrap::GetExpectedTargetNum(const Napi::CallbackInfo& info) {
+  return IntGet(info, &FIX::Session::getExpectedTargetNum);
+}
+Napi::Value SessionWrap::SetNextSenderMsgSeqNum(
+    const Napi::CallbackInfo& info) {
+  return SeqNumSet(info, /*sender=*/true, "setNextSenderMsgSeqNum");
+}
+Napi::Value SessionWrap::SetNextTargetMsgSeqNum(
+    const Napi::CallbackInfo& info) {
+  return SeqNumSet(info, /*sender=*/false, "setNextTargetMsgSeqNum");
+}
+
+// --- runtime options ---------------------------------------------------------
+
+#define NQ_BOOL_OPTION(Name)                                                   \
+  Napi::Value SessionWrap::Get##Name(const Napi::CallbackInfo& info) {         \
+    return BoolGet(info, &FIX::Session::get##Name);                            \
+  }                                                                            \
+  Napi::Value SessionWrap::Set##Name(const Napi::CallbackInfo& info) {         \
+    return BoolSet(info, &FIX::Session::set##Name, "set" #Name);               \
+  }
+
+#define NQ_INT_OPTION(Name)                                                    \
+  Napi::Value SessionWrap::Get##Name(const Napi::CallbackInfo& info) {         \
+    return IntGet(info, &FIX::Session::get##Name);                             \
+  }                                                                            \
+  Napi::Value SessionWrap::Set##Name(const Napi::CallbackInfo& info) {         \
+    return IntSet(info, &FIX::Session::set##Name, "set" #Name);                \
+  }
+
+NQ_BOOL_OPTION(ResetOnLogon)
+NQ_BOOL_OPTION(ResetOnLogout)
+NQ_BOOL_OPTION(ResetOnDisconnect)
+NQ_BOOL_OPTION(RefreshOnLogon)
+NQ_BOOL_OPTION(CheckCompId)
+NQ_BOOL_OPTION(CheckLatency)
+NQ_BOOL_OPTION(PersistMessages)
+NQ_BOOL_OPTION(SendRedundantResendRequests)
+NQ_BOOL_OPTION(ValidateLengthAndChecksum)
+NQ_BOOL_OPTION(SendNextExpectedMsgSeqNum)
+NQ_BOOL_OPTION(IsNonStopSession)
+NQ_INT_OPTION(LogonTimeout)
+NQ_INT_OPTION(LogoutTimeout)
+NQ_INT_OPTION(MaxLatency)
+
+#undef NQ_BOOL_OPTION
+#undef NQ_INT_OPTION
+
+Napi::Value SessionWrap::GetTimestampPrecision(const Napi::CallbackInfo& info) {
+  return IntGet(info, &FIX::Session::getTimestampPrecision);
+}
+
+// FIX::Session::setTimestampPrecision silently ignores values outside 0..9;
+// surface that as a RangeError instead of a no-op.
+Napi::Value SessionWrap::SetTimestampPrecision(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsNumber()) {
+    throw Napi::TypeError::New(env, "setTimestampPrecision(precision: number)");
+  }
+  const double raw = info[0].As<Napi::Number>().DoubleValue();
+  if (!std::isfinite(raw) || std::floor(raw) != raw || raw < 0 || raw > 9) {
+    throw Napi::RangeError::New(
+        env, "setTimestampPrecision: precision must be an integer in 0..9");
+  }
+  NQ_TRY(env) {
+    Resolve().setTimestampPrecision(static_cast<int>(raw));
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+// --- control ------------------------------------------------------------------
+// FIX::Session::logon()/logout() only flip SessionState's `enabled` flag and
+// `logoutReason` (the latter under SessionState's own mutex), and refresh()
+// re-reads the store under that same mutex; none of them take
+// FIX::Session::m_mutex or fire a callback, so they cannot deadlock the JS
+// thread against a QuickFIX thread blocked in a handler. That is the property
+// that lets them run here. What they are NOT is race-free: `enabled` is a
+// plain bool that SessionState::enabled(bool) stores with no lock and that
+// the engine's network thread reads in Session::next() under Session::m_mutex
+// -- formally a data race (ThreadSanitizer reports it), the same one
+// FIX::Initiator::stop() makes when it calls logout()/logon() on every session
+// from the stopping thread. In practice the network thread observes the flag
+// on its next pass; this binding does not patch QuickFIX to make it atomic.
+// Keeping them synchronous also keeps them ORDERED: as AsyncWorkers,
+// `logout(); logon();` could have run on two pool threads in either order.
+//
+// FIX::Session::disconnect() and reset() are deliberately NOT exposed. Through
+// the session's responder they reach FIX::SocketMonitor::drop(), which mutates
+// the monitor's socket sets with no lock while the engine's network thread
+// iterates them in SocketMonitor::block(); QuickFIX only ever calls them from
+// that thread itself (upstream issue #346, closed "not planned"). Any thread
+// this binding could run them on -- JS or libuv -- races it. logout() is the
+// supported way to bring a session down from the application.
+
+Napi::Value SessionWrap::Logon(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  NQ_TRY(env) {
+    Resolve().logon();
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+Napi::Value SessionWrap::Logout(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  std::string reason;
+  if (info.Length() >= 1 && !info[0].IsUndefined()) {
+    if (!info[0].IsString()) {
+      throw Napi::TypeError::New(env, "logout(reason?: string)");
+    }
+    reason = info[0].As<Napi::String>().Utf8Value();
+  }
+  NQ_TRY(env) {
+    Resolve().logout(reason);
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+// May throw IOException from the message store (mapped to QuickFixError).
+Napi::Value SessionWrap::Refresh(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  NQ_TRY(env) {
+    Resolve().refresh();
+    return env.Undefined();
+  } NQ_CATCH(env)
+}
+
+}  // namespace napi_quickfix

package/cpp/session_wrap.h

@@ -0,0 +1,144 @@
+#ifndef NAPI_QUICKFIX_SESSION_WRAP_H
+#define NAPI_QUICKFIX_SESSION_WRAP_H
+
+#include <napi.h>
+
+#include <memory>
+
+#include "quickfix/Session.h"
+#include "quickfix/SessionID.h"
+#include "session_op_gate.h"
+
+namespace napi_quickfix {
+
+// Napi::ObjectWrap giving JS a handle on a live FIX::Session.
+//
+// Lifetime: FIX::Session objects are OWNED BY THE ENGINE (Initiator/Acceptor)
+// and FIX::Session::lookupSession returns a raw, non-owning pointer. This wrap
+// therefore never caches that pointer: it stores the FIX::SessionID by value
+// plus the SessionOpGate of the engine that owned the session when the handle
+// was created, and re-resolves on EVERY call, throwing a QuickFixError with
+// fixErrorName 'SessionNotFound' once the engine has been stopped (which
+// destroys its sessions). The gate is what ties the handle to ONE engine: the
+// process-wide registry lookupSession() reads is keyed by SessionID alone, so
+// after the owner is stopped a new engine may register the same id, and a
+// handle that only re-resolved the id would silently operate on the new
+// engine's session. Resolve() therefore also requires the registered owner of
+// the id (SessionOpGate::Lookup) to still be the gate captured at creation.
+//
+//   new SessionWrap(sessionID: SessionIDWrap)   -- internal; JS reaches a
+//   Session through lookupSession() / engine.getSession(), which bind the
+//   gate via NewInstance(). A handle built any other way has no gate and
+//   always throws SessionNotFound.
+//
+// Every member is synchronous and safe on the JS thread: none takes
+// FIX::Session::m_mutex, which QuickFIX holds across application callbacks.
+//   getSessionID, isLoggedOn, isEnabled, sentLogon, sentLogout, receivedLogon,
+//   isInitiator, isAcceptor, isSessionTime(nowMs?), isLogonTime(nowMs?),
+//   getExpectedSenderNum, getExpectedTargetNum, setNextSenderMsgSeqNum,
+//   setNextTargetMsgSeqNum, logon, logout(reason?), refresh, and the runtime
+//   option getters/setters.
+// FIX::Session::disconnect()/reset() are not exposed: they are only safe on
+// the engine's own network thread (see session_wrap.cpp).
+class SessionWrap : public Napi::ObjectWrap<SessionWrap> {
+ public:
+  static Napi::Object Init(Napi::Env env, Napi::Object exports);
+
+  // Build a JS Session bound to a copy of `id` and to `gate`, the
+  // SessionOpGate of the engine owning the session (SessionOpGate::Lookup(id)
+  // or the engine wrap's own gate_). Does NOT check that the session exists;
+  // callers (lookupSession / engine.getSession) do.
+  static Napi::Object NewInstance(Napi::Env env, const FIX::SessionID& id,
+                                  std::shared_ptr<SessionOpGate> gate);
+
+  explicit SessionWrap(const Napi::CallbackInfo& info);
+
+  const FIX::SessionID& SessionID() const { return id_; }
+
+ private:
+  static Napi::FunctionReference constructor_;
+
+  // Resolve the live FIX::Session of the engine this handle was created for,
+  // or throw FIX::SessionNotFound (session gone, or the id now belongs to a
+  // different engine). Must be called inside NQ_TRY so the exception maps to a
+  // QuickFixError.
+  FIX::Session& Resolve();
+
+  Napi::Value GetSessionID(const Napi::CallbackInfo& info);
+
+  Napi::Value IsLoggedOn(const Napi::CallbackInfo& info);
+  Napi::Value IsEnabled(const Napi::CallbackInfo& info);
+  Napi::Value SentLogon(const Napi::CallbackInfo& info);
+  Napi::Value SentLogout(const Napi::CallbackInfo& info);
+  Napi::Value ReceivedLogon(const Napi::CallbackInfo& info);
+  Napi::Value IsInitiator(const Napi::CallbackInfo& info);
+  Napi::Value IsAcceptor(const Napi::CallbackInfo& info);
+  Napi::Value IsSessionTime(const Napi::CallbackInfo& info);
+  Napi::Value IsLogonTime(const Napi::CallbackInfo& info);
+
+  Napi::Value GetExpectedSenderNum(const Napi::CallbackInfo& info);
+  Napi::Value GetExpectedTargetNum(const Napi::CallbackInfo& info);
+  Napi::Value SetNextSenderMsgSeqNum(const Napi::CallbackInfo& info);
+  Napi::Value SetNextTargetMsgSeqNum(const Napi::CallbackInfo& info);
+
+  // Runtime options (plain members on FIX::Session; no locking, no callbacks).
+  Napi::Value GetResetOnLogon(const Napi::CallbackInfo& info);
+  Napi::Value SetResetOnLogon(const Napi::CallbackInfo& info);
+  Napi::Value GetResetOnLogout(const Napi::CallbackInfo& info);
+  Napi::Value SetResetOnLogout(const Napi::CallbackInfo& info);
+  Napi::Value GetResetOnDisconnect(const Napi::CallbackInfo& info);
+  Napi::Value SetResetOnDisconnect(const Napi::CallbackInfo& info);
+  Napi::Value GetRefreshOnLogon(const Napi::CallbackInfo& info);
+  Napi::Value SetRefreshOnLogon(const Napi::CallbackInfo& info);
+  Napi::Value GetCheckCompId(const Napi::CallbackInfo& info);
+  Napi::Value SetCheckCompId(const Napi::CallbackInfo& info);
+  Napi::Value GetCheckLatency(const Napi::CallbackInfo& info);
+  Napi::Value SetCheckLatency(const Napi::CallbackInfo& info);
+  Napi::Value GetPersistMessages(const Napi::CallbackInfo& info);
+  Napi::Value SetPersistMessages(const Napi::CallbackInfo& info);
+  Napi::Value GetSendRedundantResendRequests(const Napi::CallbackInfo& info);
+  Napi::Value SetSendRedundantResendRequests(const Napi::CallbackInfo& info);
+  Napi::Value GetValidateLengthAndChecksum(const Napi::CallbackInfo& info);
+  Napi::Value SetValidateLengthAndChecksum(const Napi::CallbackInfo& info);
+  Napi::Value GetSendNextExpectedMsgSeqNum(const Napi::CallbackInfo& info);
+  Napi::Value SetSendNextExpectedMsgSeqNum(const Napi::CallbackInfo& info);
+  Napi::Value GetIsNonStopSession(const Napi::CallbackInfo& info);
+  Napi::Value SetIsNonStopSession(const Napi::CallbackInfo& info);
+  Napi::Value GetLogonTimeout(const Napi::CallbackInfo& info);
+  Napi::Value SetLogonTimeout(const Napi::CallbackInfo& info);
+  Napi::Value GetLogoutTimeout(const Napi::CallbackInfo& info);
+  Napi::Value SetLogoutTimeout(const Napi::CallbackInfo& info);
+  Napi::Value GetMaxLatency(const Napi::CallbackInfo& info);
+  Napi::Value SetMaxLatency(const Napi::CallbackInfo& info);
+  Napi::Value GetTimestampPrecision(const Napi::CallbackInfo& info);
+  Napi::Value SetTimestampPrecision(const Napi::CallbackInfo& info);
+
+  // Control. All sync: they only touch SessionState under its own mutex,
+  // which QuickFIX never holds across a callback.
+  Napi::Value Logon(const Napi::CallbackInfo& info);
+  Napi::Value Logout(const Napi::CallbackInfo& info);
+  Napi::Value Refresh(const Napi::CallbackInfo& info);
+
+  // Shared helpers for the one-liner getters/setters above.
+  template <typename Fn>
+  Napi::Value BoolGet(const Napi::CallbackInfo& info, Fn fn);
+  template <typename Fn>
+  Napi::Value IntGet(const Napi::CallbackInfo& info, Fn fn);
+  template <typename Fn>
+  Napi::Value BoolSet(const Napi::CallbackInfo& info, Fn fn, const char* name);
+  template <typename Fn>
+  Napi::Value IntSet(const Napi::CallbackInfo& info, Fn fn, const char* name);
+  Napi::Value TimeCheck(const Napi::CallbackInfo& info, bool logonTime);
+  Napi::Value SeqNumSet(const Napi::CallbackInfo& info, bool sender,
+                        const char* name);
+
+  FIX::SessionID id_;
+  // The owning engine's gate at creation; held by shared_ptr so the object
+  // stays alive (and its address unique) as long as the handle does. nullptr
+  // for a handle not created through NewInstance().
+  std::shared_ptr<SessionOpGate> gate_;
+};
+
+}  // namespace napi_quickfix
+
+#endif  // NAPI_QUICKFIX_SESSION_WRAP_H

package/dist/cjs/acceptor.d.ts

@@ -0,0 +1,29 @@
+import { Engine, type EngineOptions } from './engine.js';
+export type { EngineOptions } from './engine.js';
+/**
+ * A FIX session acceptor (wraps `FIX::SocketAcceptor`). Acceptors listen for
+ * inbound connections from initiators as configured in
+ * {@link EngineOptions.settings}.
+ *
+ * Extends {@link Engine} (an {@link import('node:events').EventEmitter}), so you
+ * can observe lifecycle/message events in addition to supplying `handlers`.
+ * Remember: only `handlers` may mutate outbound messages or reject inbound ones;
+ * events are observe-only.
+ *
+ * @example
+ * ```ts
+ * const acceptor = new Acceptor({
+ *   settings: SessionSettings.fromString(cfg),
+ *   handlers: {
+ *     fromApp: (msg, id) => { void sendToTarget(makeReply(msg), id); },
+ *   },
+ * });
+ * await acceptor.start();
+ * // ... later
+ * await acceptor.stop();
+ * ```
+ */
+export declare class Acceptor extends Engine {
+    /** @param options Engine options. */
+    constructor(options: EngineOptions);
+}

package/dist/cjs/acceptor.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Acceptor = void 0;
+/**
+ * FIX session acceptor (server side — listens for initiators).
+ */
+const native_js_1 = require("./native.js");
+const engine_js_1 = require("./engine.js");
+/**
+ * A FIX session acceptor (wraps `FIX::SocketAcceptor`). Acceptors listen for
+ * inbound connections from initiators as configured in
+ * {@link EngineOptions.settings}.
+ *
+ * Extends {@link Engine} (an {@link import('node:events').EventEmitter}), so you
+ * can observe lifecycle/message events in addition to supplying `handlers`.
+ * Remember: only `handlers` may mutate outbound messages or reject inbound ones;
+ * events are observe-only.
+ *
+ * @example
+ * ```ts
+ * const acceptor = new Acceptor({
+ *   settings: SessionSettings.fromString(cfg),
+ *   handlers: {
+ *     fromApp: (msg, id) => { void sendToTarget(makeReply(msg), id); },
+ *   },
+ * });
+ * await acceptor.start();
+ * // ... later
+ * await acceptor.stop();
+ * ```
+ */
+class Acceptor extends engine_js_1.Engine {
+    /** @param options Engine options. */
+    constructor(options) {
+        super(native_js_1.native.AcceptorWrap, options);
+    }
+}
+exports.Acceptor = Acceptor;