defmodule Dimse do
  @moduledoc """
  Pure Elixir DICOM DIMSE networking library.

  Provides the DICOM Upper Layer Protocol (PS3.8) and DIMSE-C message services
  (PS3.7) for building DICOM SCP (server) and SCU (client) applications on the BEAM.

  ## Public API

  ### Listener (SCP)

      Dimse.start_listener(port: 11112, handler: MyApp.DicomHandler)
      Dimse.stop_listener(ref)

  ### Client (SCU)

      {:ok, assoc} = Dimse.connect("192.168.1.10", 11112, calling_ae: "MY_SCU", called_ae: "REMOTE_SCP")
      :ok = Dimse.echo(assoc)
      :ok = Dimse.store(assoc, sop_class_uid, sop_instance_uid, data_set)
      {:ok, results} = Dimse.find(assoc, :study, query)
      :ok = Dimse.move(assoc, :study, query, dest_ae: "DEST_AE")
      {:ok, data_sets} = Dimse.get(assoc, :study, query)
      :ok = Dimse.release(assoc)
      :ok = Dimse.abort(assoc)

  ## Architecture

  Each DICOM association is a dedicated GenServer process (`Dimse.Association`)
  supervised under a DynamicSupervisor. Ranch handles TCP acceptance. This gives
  fault isolation per-association and natural backpressure via `max_children`.

  ## Dependencies

  - `dicom` — command set encoding (Implicit VR Little Endian), UID generation,
    transfer syntax registry, SOP class lookup
  - `ranch` — TCP acceptor pool
  - `telemetry` — observability events
  """

  @doc """
  Starts a DIMSE listener on the given port.

  ## Options

    * `:port` — TCP port to listen on (default: `11112`)
    * `:handler` — module implementing `Dimse.Handler` behaviour (required)
    * `:ae_title` — local AE title (default: `"DIMSE"`)
    * `:max_associations` — max concurrent associations (default: `200`)
    * `:num_acceptors` — Ranch acceptor pool size (default: `10`)
    * `:max_pdu_length` — max PDU length in bytes (default: `16_384`)

  Returns `{:ok, listener_ref}` or `{:error, reason}`.
  """
  @spec start_listener(keyword()) :: {:ok, term()} | {:error, term()}
  def start_listener(opts \\ []) do
    Dimse.Listener.start(opts)
  end

  @doc """
  Stops a running DIMSE listener.
  """
  @spec stop_listener(term()) :: :ok | {:error, term()}
  def stop_listener(ref) do
    Dimse.Listener.stop(ref)
  end

  @doc """
  Opens an association to a remote DICOM AE (SCU client).

  ## Options

    * `:calling_ae` — local AE title (default: `"DIMSE"`)
    * `:called_ae` — remote AE title (default: `"ANY-SCP"`)
    * `:abstract_syntaxes` — list of SOP Class UIDs to propose
    * `:transfer_syntaxes` — list of Transfer Syntax UIDs to propose
    * `:max_pdu_length` — max PDU length (default: `16_384`)
    * `:timeout` — connection timeout in ms (default: `30_000`)

  Returns `{:ok, association_pid}` or `{:error, reason}`.
  """
  @spec connect(String.t(), pos_integer(), keyword()) :: {:ok, pid()} | {:error, term()}
  def connect(host, port, opts \\ []) do
    Dimse.Scu.open(host, port, opts)
  end

  @doc "Sends a C-ECHO request on an established association."
  @spec echo(pid(), keyword()) :: :ok | {:error, term()}
  def echo(assoc, opts \\ []), do: Dimse.Scu.Echo.verify(assoc, opts)

  @doc """
  Sends a C-STORE request with the given data set.

  ## Parameters

    * `assoc` — association pid from `Dimse.connect/3`
    * `sop_class_uid` — SOP Class UID of the instance
    * `sop_instance_uid` — SOP Instance UID of the instance
    * `data` — encoded data set binary

  ## Options

    * `:priority` — request priority (default: `0x0000` medium)
    * `:move_originator_ae` — AE title of the C-MOVE originator
    * `:move_originator_message_id` — message ID from the C-MOVE request
    * `:timeout` — response timeout in ms (default: `30_000`)
  """
  @spec store(pid(), String.t(), String.t(), binary(), keyword()) :: :ok | {:error, term()}
  def store(assoc, sop_class_uid, sop_instance_uid, data, opts \\ []) do
    Dimse.Scu.Store.send(assoc, sop_class_uid, sop_instance_uid, data, opts)
  end

  @doc "Sends a C-FIND request and returns matching results."
  @spec find(pid(), atom(), term()) :: {:ok, [term()]} | {:error, term()}
  def find(_assoc, _level, _query), do: {:error, :not_implemented}

  @doc "Sends a C-MOVE request to retrieve studies to a destination AE."
  @spec move(pid(), atom(), term(), keyword()) :: :ok | {:error, term()}
  def move(_assoc, _level, _query, _opts \\ []), do: {:error, :not_implemented}

  @doc "Sends a C-GET request to retrieve studies on the same association."
  @spec get(pid(), atom(), term()) :: {:ok, [term()]} | {:error, term()}
  def get(_assoc, _level, _query), do: {:error, :not_implemented}

  @doc "Sends an A-RELEASE-RQ to gracefully close the association."
  @spec release(pid(), timeout()) :: :ok | {:error, term()}
  def release(assoc, timeout \\ 30_000), do: Dimse.Scu.release(assoc, timeout)

  @doc "Sends an A-ABORT to forcefully terminate the association."
  @spec abort(pid()) :: :ok
  def abort(assoc), do: Dimse.Scu.abort(assoc)
end