FIX.Session

An initiator-side FIX session engine for Elixir.

FIX.Session uses :gen_statem to manage connection lifecycle, FIX sequence numbers, logon/logout, heartbeats, gap recovery, persistence, and delivery of validated application messages. FIX 4.4 over TCP is the default configuration.

Status: Early development (0.1.0). The API and storage format may change. See Current limitations before using this library in production.

Features

• Initiator-side TCP sessions with automatic reconnects
• Logon, Logout, Heartbeat, TestRequest, ResendRequest, and SequenceReset handling
• Independent inbound and outbound liveness timers
• Inbound sequence validation, gap buffering, and duplicate suppression
• Atomic persistence of outbound wire data and the next outbound sequence number
• Pluggable transport and session-store behaviours
• Application delivery only after session and sequence validation
• Pure protocol transitions that can be tested without sockets or processes

Installation

Add fix_session to your dependencies in mix.exs:

def deps do
  [
    {:fix_session, "~> 0.1.0"}
  ]
end

Then fetch the dependency with mix deps.get.

The project requires Elixir ~> 1.19.

Getting started

A session does not start or own its store. The store must start first and outlive every session that uses it. Supervise the store and session with :rest_for_one so a store failure also restarts dependent sessions:

defmodule MyApp.FIXSupervisor do
  use Supervisor

  @impl true
  def start_link(options) do
    Supervisor.start_link(__MODULE__, options, name: __MODULE__)
  end

  @impl true
  def init(_options) do
    config =
      FIX.Session.Config.new!(
        session_id: :primary,
        name: MyApp.FIXSession,
        host: "fix.example.com",
        port: 4001,
        sender_comp_id: "SENDER",
        target_comp_id: "TARGET",
        app: MyApp.FIXHandler
      )

    children = [
      {FIX.Session.Store.ETS, file: "/var/lib/my_app/fix_session.ets"},
      {FIX.Session, config}
    ]

    Supervisor.init(children, strategy: :rest_for_one)
  end
end

With its default options, FIX.Session.Store.ETS creates the named table used by the default store_ref, so no additional store configuration is necessary.

The session connects immediately, sends Logon, and reconnects every five seconds after an ordinary connection failure. A session is available for application messages only after the counterparty's Logon has been accepted.

Receiving application messages

Set :app to a module that exports handle_message/2. The callback runs synchronously in the session process and receives the validated FIX.Message and session config:

defmodule MyApp.FIXHandler do
  def handle_message(%FIX.Message{} = message, %FIX.Session.Config{} = config) do
    send(MyApp.OrderManager, {:fix_message, config.session_id, message})
    :ok
  end
end

Keep this callback fast and non-blocking. If no :app module is configured, validated application messages are discarded.

Sending application messages

Pass a FIX.Message to the running session:

message = %FIX.Message{
  msg_type: "D",
  body: [
    # Application fields for NewOrderSingle
  ]
}

:ok = FIX.Session.send_message(MyApp.FIXSession, message)

The session assigns and overwrites session-controlled fields, including BeginString(8), MsgSeqNum(34), SenderCompID(49), SendingTime(52), and TargetCompID(56). It persists the encoded message and advances next_out before writing to the socket.

Calling send_message/2 before Logon completes returns:

{:error, {:not_logged_on, current_state}}

Logging out

:ok = FIX.Session.logout(MyApp.FIXSession, "Application shutdown")

An operator-requested logout is terminal for that process: after the Logout exchange or timeout, it remains disconnected rather than reconnecting automatically. Restart the supervised session to establish a new connection.

Configuration

Create a validated %FIX.Session.Config{} with FIX.Session.Config.new!/1.

Required options

Common optional settings

Advanced integrations can replace :transport, :store, and :store_ref with modules and references implementing FIX.Session.Transport and FIX.Session.Store.

Persistence

FIX.Session.Store.ETS is the default store. Its table is owned by a dedicated supervised process, so sequence numbers and outbound messages survive a session-process crash or reconnect.

The ETS store is not fully crash durable:

• Without :file, state is lost when the store process or VM exits.
• With :file, state is restored at startup and snapshotted during graceful store shutdown.
• A hard crash can leave the snapshot stale. Restoring stale outbound sequence state can reuse sequence numbers that were already sent.

Use the ETS snapshot only when those guarantees are acceptable. Production deployments requiring crash durability should implement FIX.Session.Store with transactional durable storage. FIX.Session.Store.Memory is intended for tests and development.

For isolated ETS stores, start the owner with name: nil, retrieve its table with FIX.Session.Store.ETS.table/1, and pass that table as :store_ref in the session config.

Current limitations

• Initiator sessions only; there is no acceptor/listener implementation.
• The included transport supports TCP only; TLS is not yet included.
• FIX 4.4 is the tested/default dictionary and protocol target.
• Inbound ResendRequests are currently answered with a SequenceReset-GapFill rather than replaying stored business messages.
• ETS snapshots do not provide hard-crash durability.
• Session schedules, bounded outbound retention, telemetry, and formal FIX conformance testing are not yet implemented.
• reset_on_logon: true is explicitly unsupported.

Development

Fetch dependencies and run the test suite:

mix deps.get
mix test

Format and compile with warnings treated as errors:

mix format --check-formatted
mix compile --warnings-as-errors

License

Licensed under the Apache License 2.0. See LICENSE.