spoke

spoke

Types

AuthDetails

</>

Authentication details passed to the server when connecting. Remember that these are not encrypted, unless working with an encrypted transport channel.

pub type AuthDetails {
  AuthDetails(username: String, password: Option(BitArray))
}

Constructors 

  • AuthDetails(username: String, password: Option(BitArray))

Client

opaque </>

An opaque handle for the MQTT client. Can live across multiple sessions and connections, or resume sessions that were previously disconnected. Under the hood, the client is an OTP actor.

pub opaque type Client

ConnectError

</>

Error code from the server - we got a response, but there was an error.

pub type ConnectError {
  UnacceptableProtocolVersion
  IdentifierRefused
  ServerUnavailable
  BadUsernameOrPassword
  NotAuthorized
}

Constructors 

  • UnacceptableProtocolVersion

    The MQTT server doesn’t support MQTT 3.1.1

  • IdentifierRefused

    The Client identifier is correct UTF-8 but not allowed by the Server

  • ServerUnavailable

    The Network Connection has been made but the MQTT service is unavailable

  • BadUsernameOrPassword

    The data in the user name or password is malformed

  • NotAuthorized

    The Client is not authorized to connect

ConnectOptions

</>

The set of options used to establish a connection to the server. Includes the set of data that should generally not change across multiple connect calls (if they are needed).

pub type ConnectOptions {
  ConnectOptions(
    connector: TransportChannelConnector,
    client_id: String,
    authentication: Option(AuthDetails),
    keep_alive_seconds: Int,
    server_timeout_ms: Int,
  )
}

Constructors 

  • ConnectOptions(
  connector: TransportChannelConnector,
  client_id: String,
  authentication: Option(AuthDetails),
  keep_alive_seconds: Int,
  server_timeout_ms: Int,
)

    Arguments

    • connector

      Function to establish a transport channel.

    • client_id

      The MQTT client ID used when connecting to the server.

    • authentication

      Optional username and (additionally optional) password

    • keep_alive_seconds

      Keep-alive interval in seconds (MQTT spec doesn’t allow more granular control)

    • server_timeout_ms

      “Reasonable amount of time” for the server to respond (including network latency), as used in the MQTT specification.

ConnectionState

</>

Represents the state of the connection to the server.

pub type ConnectionState {
  ConnectFailed(String)
  ConnectRejected(ConnectError)
  ConnectAccepted(session_present: Bool)
  Disconnected
  DisconnectedUnexpectedly(reason: String)
}

Constructors 

  • ConnectFailed(String)

    Connecting to the server failed before we got a response to the connect packet.

  • ConnectRejected(ConnectError)

    The server was reachable, but rejected our connect packet

  • ConnectAccepted(session_present: Bool)

    The server has accepted our connect packet

  • Disconnected

    Disconnected as a result of calling disconnect

  • DisconnectedUnexpectedly(reason: String)

    The connection was dropped for an unexpected reason, e.g. a transport channel error or protocol violation.

OperationError

</>

Unified error type for operations that are completed in a blocking way.

pub type OperationError {
  NotConnected
  OperationTimedOut
  ProtocolViolation
  KilledDuringOperation
}

Constructors 

  • NotConnected

    The client was not connected when it was required.

  • OperationTimedOut

    The operation did not complete in time.

  • ProtocolViolation

    We received unexpected data from the server, and will disconnect.

  • KilledDuringOperation

    The client actor was killed while the operation was in progress.

PublishData

</>

A convenience record to hold all the data used when publishing messages.

pub type PublishData {
  PublishData(
    topic: String,
    payload: BitArray,
    qos: QoS,
    retain: Bool,
  )
}

Constructors 

  • PublishData(
  topic: String,
  payload: BitArray,
  qos: QoS,
  retain: Bool,
)

QoS

</>

Quality of Service levels, as specified in the MQTT specification

pub type QoS {
  AtMostOnce
  AtLeastOnce
  ExactlyOnce
}

Constructors 

  • AtMostOnce

    The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.

  • AtLeastOnce

    This quality of service ensures that the message arrives at the receiver at least once.

  • ExactlyOnce

    This is the highest quality of service, for use when neither loss nor duplication of messages are acceptable. There is an increased overhead associated with this quality of service.

SubscribeRequest

</>

Utility record for the data required to request a subscription.

pub type SubscribeRequest {
  SubscribeRequest(filter: String, qos: QoS)
}

Constructors 

  • SubscribeRequest(filter: String, qos: QoS)

Subscription

</>

The result of a subscribe operation

pub type Subscription {
  SuccessfulSubscription(topic_filter: String, qos: QoS)
  FailedSubscription(topic_filter: String)
}

Constructors 

  • SuccessfulSubscription(topic_filter: String, qos: QoS)

    The subscribe succeeded with the specified QoS level.

  • FailedSubscription(topic_filter: String)

    The server returned a failure for requested subscription.

TransportChannelConnector

</>

A function that connects a transport channel and returns the send, receive, and shutdown functions or an error. NOTE: This only uses standard library and Erlang types, so that implementors do not need to depend on the Spoke package.

pub type TransportChannelConnector =
  fn() ->
    Result(
      #(
        fn(BytesTree) -> Result(Nil, String),
        fn() -> Selector(Result(BitArray, String)),
        fn() -> Nil,
      ),
      String,
    )

Update

</>

Represents a received message or change in the client.

pub type Update {
  ReceivedMessage(
    topic: String,
    payload: BitArray,
    retained: Bool,
  )
  ConnectionStateChanged(ConnectionState)
}

Constructors 

  • ReceivedMessage(topic: String, payload: BitArray, retained: Bool)

    A published message to a topic this client was subscribed to was received.

  • ConnectionStateChanged(ConnectionState)

    The connection state of this client changed.

Functions

connect

</> 
pub fn connect(client: Client, clean_session: Bool) -> Nil

Starts connecting to the MQTT server. The connection state will be published as an update. If a connection is already established or being established, this will be a no-op. Note that switching between clean_session values while already connecting is currently not well handled.

connect_with_id

</> 
pub fn connect_with_id(
  connector: fn() ->
    Result(
      #(
        fn(BytesTree) -> Result(Nil, String),
        fn() -> Selector(Result(BitArray, String)),
        fn() -> Nil,
      ),
      String,
    ),
  client_id: String,
) -> ConnectOptions

Constructs connect options from transport options, the given client id, and default settings for the rest of the options.

connect_with_will

</> 
pub fn connect_with_will(
  client: Client,
  clean_session: Bool,
  will: PublishData,
) -> Nil

Same as connect, but specifies a will message for this connection.

disconnect

</> 
pub fn disconnect(client: Client) -> String

Disconnects from the MQTT server. The connection state change will also be published as an update. If a connection is not established or being established, this will be a no-op. Returns the serialized session state to be potentially restored later.

keep_alive_seconds

</> 
pub fn keep_alive_seconds(
  options: ConnectOptions,
  keep_alive_seconds: Int,
) -> ConnectOptions

Builder function for specifying the keep-alive time in the connect options.

pending_publishes

</> 
pub fn pending_publishes(client: Client) -> Int

Returns the number of QoS > 0 publishes that haven’t yet been completely published. Also see wait_for_publishes_to_finish.

publish

</> 
pub fn publish(client: Client, data: PublishData) -> Nil

Connects to the MQTT server. Will disconnect if the connect times out, and send the Disconnect update. Note that in case of a timeout, the message might still have been already published.

restore_session

</> 
pub fn restore_session(
  connect_options: ConnectOptions,
  state: String,
) -> Result(Client, String)

Restores an MQTT session from a previously stored state, as returned by disconnect. Will return an error if the session state can not be restored from the provided string. Does not connect to the server, until connect is called.

server_timeout_ms

</> 
pub fn server_timeout_ms(
  options: ConnectOptions,
  server_timeout_ms: Int,
) -> ConnectOptions

Builder function for specifying the server operation timeout in the connect options.

start_session

</> 
pub fn start_session(connect_options: ConnectOptions) -> Client

Starts a new MQTT session with the given options. Does not connect to the server, until connect is called.

subscribe

</> 
pub fn subscribe(
  client: Client,
  topics: List(SubscribeRequest),
) -> Result(List(Subscription), OperationError)

Subscribes to the given topics. Will block until we get a response from the server, returning the result of the operation.

unsubscribe

</> 
pub fn unsubscribe(
  client: Client,
  topics: List(String),
) -> Result(Nil, OperationError)

Unsubscribes from the given topics. Will block until we get a response from the server, returning the result of the operation.

updates

</> 
pub fn updates(client: Client) -> Subject(Update)

Returns a Subject for receiving client updates (received messages and connection state changes). NOTE: This function is provided for convenience as receiving updates only works from the process that created the client! Future versions of spoke might support receiving updates in multiple processes.

using_auth

</> 
pub fn using_auth(
  options: ConnectOptions,
  username: String,
  password: Option(BitArray),
) -> ConnectOptions

Builder function for specifying the authentication details to be used when connecting.

wait_for_publishes_to_finish

</> 
pub fn wait_for_publishes_to_finish(
  client: Client,
  timeout: Int,
) -> Result(Nil, Nil)

Wait for all pending QoS > 0 publishes to complete. Returns an error if the operation times out, or client is killed while waiting.

✨ Search Document