ACDS Client

Client-side session discovery, authentication, and signaling API.

Client-side session discovery, authentication, and signaling API.

This is the client half of ACDS: it connects to the discovery service, resolves a session string, joins the session, and carries the metadata needed to move on to the media connection.

If you are writing a client, this is the moment where a human-readable session name becomes a real connection. The client opens one authenticated ACIP connection to ACDS, asks what a session means, and—after the user has proved they are allowed to join—receives the endpoint information needed to connect to the host. ACDS coordinates that hand-off; it never carries the video or audio itself.

ACDS Client Protocol

Protocol Overview

• Transport: TCP (default port 27225, configurable)
• Protocol: ACIP binary protocol (not HTTP/JSON)
• Packet Format: packet_header_t + payload (see network/acip/protocol.h)
• Authentication: Ed25519 identity signatures and the configured crypto policy
• Encryption: ACIP session protection negotiated on the discovery connection
• Validation: CRC32 checksum on every packet payload

Session Lifecycle (Client Perspective)

1. Discovery (Optional): Lookup existing session by string
   • Send: SESSION_LOOKUP packet with session_string
   • Recv: SESSION_INFO packet with session metadata (no connection details)
2. Creation (Host): Create new session and become host
   • Send: SESSION_CREATE packet with host public key + signature
   • Recv: SESSION_CREATED packet with session_id, participant_id, STUN/TURN servers
   • Server assigns participant ID and tracks session in database
3. Join (Guest): Connect to existing session
   • Send: SESSION_JOIN packet with credentials (password or identity)
   • Recv: SESSION_JOINED packet with server address, TURN credentials
   • Server verifies credentials and reveals IP:port to authenticated client
4. P2P Negotiation (Discovery Mode):
   • Send/Recv: WEBRTC_SDP packets for offer/answer
   • Send/Recv: WEBRTC_ICE packets for candidate exchange
   • Negotiate best connection (host election if no host exists)
5. Disconnect: Leave session cleanly
   • Send: SESSION_LEAVE packet
   • Recv: SESSION_END notification when all participants leave

Packet Type Summary

• SESSION_CREATE (6000): Host creates new session
• SESSION_CREATED (6001): Discovery confirms creation
• SESSION_LOOKUP (6002): Client queries for session
• SESSION_INFO (6003): Discovery returns metadata
• SESSION_JOIN (6004): Guest requests to join
• SESSION_JOINED (6005): Discovery confirms join with details
• SESSION_LEAVE (6006): Client notifies disconnect
• SESSION_END (6007): Discovery notifies session closed
• WEBRTC_SDP (6009): P2P session description
• WEBRTC_ICE (6010): P2P ICE candidate

Connection Configuration

The acds_client_config_t structure specifies:

• Server address (IPv4, IPv6, or hostname)
• Server port (default: 27225)
• Timeout (connection timeout in milliseconds)
• Optional callback for graceful shutdown

A minimal lookup-and-join flow looks like this:

acds_client_t client = {0};
acds_client_config_t config;
acds_client_config_init_defaults(&config);
 
if (acds_client_connect(&client, &config) == ASCIICHAT_OK) {
  acds_session_lookup_result_t info = {0};
  if (acds_session_lookup(&client, "happy-sunset-ocean", &info) == ASCIICHAT_OK && info.found) {
    // Fill acds_session_join_params_t with the participant identity/password.
    // The successful join result contains the host endpoint and session type.
  }
  acds_client_disconnect(&client);
}

ACIP Protocol Overview:

• Binary TCP protocol (not HTTP/JSON)
• Packet-based with CRC32 validation
• Ed25519 identity signatures (alternative to password auth)
• Optional password protection
• UUID identifiers for sessions and participants (16 bytes each)

Primary Use Case: Connecting to ACDS (ascii-chat Discovery Service) servers for session discovery and WebRTC peer coordination.

Integration: This library is part of libasciichat and can be used by any application needing ACIP/ACDS integration.

See also

network/acip/acds.h for ACDS message structures

network/acip/protocol.h for ACIP packet types and protocol version

network/acip/transport.h for transport abstraction layer

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Version

1.0 (ACDS Client API)