# SPDX-License-Identifier: MIT
# Copyright (c) 2025 Scott Thompson

defmodule ArduinoRouter.Transport do
  @moduledoc """
  A behaviour for sending messages to an Arduino over a transport layer.

  This is split out into an independent behaviour to allow mocking in tests.
  """

  @typedoc "state maintained on behalf of the transport layer"
  @type state() :: term()

  @typedoc "A result from a call to `start/2`"
  @type start_result() :: {:ok, state()} | {:error, term()}

  @typedoc "A result from a call to `send_message/2`"
  @type send_result() :: {:ok, state()} | {:error, term()}

  @doc """
  Start the transport layer and return the state token.

  The receiver is the PID that will receive incoming RPC messages from the
  transport layer. RPC messages are sent to this PID as process messages in
  the format `{:incoming_rpc, rpc_message}`.
  """
  @callback start(receiver :: pid(), options :: keyword()) :: start_result()

  @doc """
  Send a message to the Arduino router.

  Returns `{:ok, state}` on success or `{:error, reason}` on failure.
  """
  @callback send_message(state(), MessagePackRPC.rpc_message()) :: send_result()

  @doc """
  Stop the transport layer and release any resources.
  """
  @callback stop(state()) :: :ok
end