MLLP.Client (mllp v0.8.4)

MLLP.Client provides a simple tcp client for sending and receiving data via MLLP over TCP.

While MLLP is primarily used to send HL7 messages, MLLP.Client can be used to send non-hl7 messages, such as XML.

Connection Behaviour

Upon successful start up via start_link/4, the client will attempt to establish a connection to the given address on the provided port. If a connection can not be immediately established, the client will keep trying to establish a connection per the value of :auto_reconnect_interval which defaults to 1 second. Therefor it is possible that before a connection is fully established, the caller may attempt to send a message which will result in MLLP.Client.Error.t() being returned containing the last error encountered in trying to establish a connection. Additionally, said behavour could be encountered at any point during life span of an MLLP.Client process if the connection becomees severed on either side.

All connections, send, and receive failures will be logged as errors.

Examples

Sending messages as strings

iex> MLLP.Receiver.start(dispatcher: MLLP.EchoDispatcher, port: 4090)
{:ok,
%{
  pid: #PID<0.2167.0>,
  port: 4090,
  receiver_id: #Reference<0.3312799297.2467299337.218126>
}}
iex> {:ok, client} = MLLP.Client.start_link("127.0.0.1", 4090)
{:ok, #PID<0.369.0>}
iex> msg = "MSH|^~\&|MegaReg|XYZHospC|SuperOE|XYZImgCtr|20060529090131-0500|..."
"MSH|^~\&|MegaReg|XYZHospC|SuperOE|XYZImgCtr|20060529090131-0500|..."
iex> MLLP.Client.send(client, msg)
{:ok, "MSH|^~\&|SuperOE|XYZImgCtr|MegaReg|XYZHospC|20060529090131-0500||ACK^A01^ACK|..."}
iex>

Sending messages with HL7.Message.t()

iex> MLLP.Receiver.start(dispatcher: MLLP.EchoDispatcher, port: 4090)
{:ok,
%{
  pid: #PID<0.2167.0>,
  port: 4090,
  receiver_id: #Reference<0.3312799297.2467299337.218126>
}}
iex> {:ok, client} = MLLP.Client.start_link("127.0.0.1", 4090)
{:ok, #PID<0.369.0>}
iex> msg = HL7.Message.new(HL7.Examples.wikipedia_sample_hl7())
iex> MLLP.Client.send(client, msg)
{:ok, :application_accept,
    %MLLP.Ack{
    acknowledgement_code: "AA",
    hl7_ack_message: nil,
    text_message: "A real MLLP message dispatcher was not provided"
}}

Using TLS

iex> tls_opts = [
  cacertfile: "/path/to/ca_certificate.pem",
  verify: :verify_peer,
  certfile: "/path/to/server_certificate.pem",
  keyfile: "/path/to/private_key.pem"
]
iex> MLLP.Receiver.start(dispatcher: MLLP.EchoDispatcher, port: 4090, tls: tls_opts)
iex> {:ok, client} = MLLP.Client.start_link("localhost", 8154, tls: [verify: :verify_peer, cacertfile: "path/to/ca_certfile.pem"])
iex> msg = HL7.Message.new(HL7.Examples.wikipedia_sample_hl7())
iex> MLLP.Client.send(client, msg)
{:ok, :application_accept,
    %MLLP.Ack{
    acknowledgement_code: "AA",
    hl7_ack_message: nil,
    text_message: "A real MLLP message dispatcher was not provided"
}}

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Returns true if the connection is open and established, otherwise false.

Instructs the client to disconnect (if connected) and attempt a reconnect.

Sends a message and receives a response.

Sends a message without awaiting a response.

Starts a new MLLP.Client.

Stops an MLLP.Client given a MLLP.Client pid.

Link to this section Types

Link to this type

ip_address()

Specs

ip_address() :: :inet.socket_address() | String.t()

Specs

pid_ref() :: atom() | pid() | {atom(), any()} | {:via, atom(), any()}

Specs

t() :: %MLLP.Client{
  address: ip_address(),
  auto_reconnect_interval: non_neg_integer(),
  backoff: any(),
  connect_failure: term(),
  host_string: term(),
  pending_reconnect: reference() | nil,
  pid: pid() | nil,
  port: char(),
  send_opts: term(),
  socket: any(),
  socket_address: String.t(),
  socket_opts: Keyword.t(),
  tcp: module() | nil,
  telemetry_module: module() | nil,
  tls_opts: Keyword.t()
}

Link to this section Functions

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

is_connected?(pid)

Specs

is_connected?(pid :: pid()) :: boolean()

Returns true if the connection is open and established, otherwise false.

Specs

reconnect(pid :: pid()) :: :ok

Instructs the client to disconnect (if connected) and attempt a reconnect.

Link to this function

send(pid, payload, options \\ %{}, timeout \\ 5000)

Specs

send(
  pid :: pid(),
  payload :: HL7.Message.t() | String.t() | binary(),
  options :: MLLP.ClientContract.send_options(),
  timeout :: non_neg_integer()
) ::
  {:ok, String.t()}
  | MLLP.Ack.ack_verification_result()
  | {:error, MLLP.ClientContract.client_error()}

Sends a message and receives a response.

send/4 supports both HL7.Message and String.t().

All messages and responses will be wrapped and unwrapped via MLLP.Envelope.wrap_message/1 and MLLP.Envelope.unwrap_message/1 respectively

In case the payload provided is an HL7.Message.t() the acknowledgment returned from the server will always be verified via MLLP.Ack.verify_ack_against_message/2. This is the only case where an MLLP.Ack.ack_verification_result() will be returned.

Options

  • :reply_timeout - Optionally specify a timeout value for receiving a response. Must be a positive integer or :infinity. Defaults to :infinity.
Link to this function

send_async(pid, payload, timeout \\ 5000)

Sends a message without awaiting a response.

Given the synchronous nature of MLLP/HL7 this function is mainly useful for testing purposes.

Link to this function

start_link(address, port, options \\ [])

Specs

start_link(
  address :: ip_address(),
  port :: :inet.port_number(),
  options :: MLLP.ClientContract.options()
) :: {:ok, pid()}

Starts a new MLLP.Client.

MLLP.Client.start_link/4 will start a new MLLP.Client process.

This function will raise a ArgumentError if an invalid ip_address() is provided.

Options

  • :use_backoff - Specify if an exponential backoff should be used for connection. When an attempt to establish a connection fails, either post-init or at some point during the life span of the client, the backoff value will determine how often to retry a reconnection. Starts at 1 second and increases exponentially until reaching backoff_max_seconds seconds. Defaults to true.

  • :backoff_max_seconds - Specify the max limit of seconds the backoff reconection attempt should take, defauls to 180 (3 mins).

  • :auto_reconnect_interval - Specify the interval between connection attempts. Specifically, if an attempt to establish a connection fails, either post-init or at some point during the life span of the client, the value of this option shall determine how often to retry a reconnection. Defaults to 1000 milliseconds. This option will only be used if use_backoff is set to false.

  • :reply_timeout - Optionally specify a timeout value for receiving a response. Must be a positive integer or :infinity. Defaults to :infinity.

  • :socket_opts - A list of socket options as supported by :gen_tcp. Note that :binary, :packet, and :active can not be overridden.

  • :tls - A list of tls options as supported by :ssl. When using TLS it is highly recommended you set :verify to :verify_peer, select a CA trust store using the :cacertfile or :cacerts options. Additionally, further hardening can be achieved through other ssl options such as enabling certificate revocation via the :crl_check and :crl_cache options and customization of enabled protocols and cipher suites for your specific use-case. See :ssl for details.

Specs

stop(pid :: pid()) :: :ok

Stops an MLLP.Client given a MLLP.Client pid.

This function will always return :ok per GenServer.stop/1, thus you may give it a pid that references a client which is already stopped.