spoterl

Erlang client library for the Spot Protocol, providing secure real-time messaging between clients and servers.

Features

• WebSocket connection to Spot servers with TLS
• ECDSA key generation and signature
• ID card creation and management
• CBOR message encoding/decoding
• Query support for server endpoints
• g-dns.net resolver for host lookup

Installation

Add to your rebar.config dependencies:

{deps, [
    {spoterl, "0.1.0"}
]}.

Quick Start

% Start the application
application:ensure_all_started(spoterl).

% Create a new client (generates ephemeral key)
{ok, Client} = spoterl:new().

% Wait for connection to come online
ok = spoterl:wait_online(Client, 10000).

% Query server time
{ok, Time} = spoterl:get_time(Client).

% Get client's target ID (for receiving messages)
TargetId = spoterl:target_id(Client).

% Clean up
spoterl:close(Client).

Client Options

% Create client with custom options
{ok, Client} = spoterl:new([
    {keychain, Keychain},  % Use existing keychain
    {meta, #{<<"name">> => <<"MyClient">>}},  % ID card metadata
    {handlers, #{<<"custom">> => fun handle_custom/1}}  % Message handlers
]).

API

Connection

• spoterl:new() -> {ok, pid()} - Create new client with ephemeral key
• spoterl:new(Opts) -> {ok, pid()} - Create client with options
• spoterl:close(Client) -> ok - Close client and connections
• spoterl:wait_online(Client, Timeout) -> ok | {error, timeout} - Wait for connection
• spoterl:connection_count(Client) -> {Total, Online} - Get connection stats

Identity

• spoterl:target_id(Client) -> binary() - Get client's target ID (k.<hash>)
• spoterl:id_card(Client) -> idcard() - Get client's ID card

Messaging

• spoterl:query(Client, Target, Body) -> {ok, Response} | {error, Reason} - Send query and wait for response
• spoterl:query(Client, Target, Body, Timeout) -> {ok, Response} | {error, Reason} - Query with custom timeout
• spoterl:send_to(Client, Target, Payload) -> ok | {error, Reason} - Send message without waiting for response
• spoterl:get_time(Client) -> {ok, Timestamp} | {error, Reason} - Get server time

Storage

• spoterl:store_blob(Client, Key, Value) -> ok | {error, Reason} - Store encrypted blob
• spoterl:fetch_blob(Client, Key) -> {ok, Value} | {error, Reason} - Fetch encrypted blob

Handlers

% Set a message handler for an endpoint
spoterl:set_handler(Client, <<"myendpoint">>, fun(Msg) ->
    Body = spoterl_proto:get_body(Msg),
    % Process message...
    {ok, <<"response">>}  % or {error, <<"error msg">>} or ok
end).

% Remove handler
spoterl:set_handler(Client, <<"myendpoint">>, undefined).

Dependencies

• bottlerl - Bottle protocol implementation
• gun - HTTP/WebSocket client
• jiffy - JSON encoding
• uuid - UUID generation

Building

$ rebar3 compile

Testing

$ rebar3 ct

License

MIT License - see LICENSE.md