Skip to content

client-compatibility.md

Latest commit

 

History

History
121 lines (92 loc) · 5.55 KB

client-compatibility.md

File metadata and controls

121 lines (92 loc) · 5.55 KB
Raw

IRC client compatibility

Telex exposes a conventional IRC listener so existing clients remain useful, but its durable account, history, reaction, reply, and installation behavior also uses negotiated IRCv3 capabilities. A client that does not implement a Telex feature should still connect and chat normally.

This page distinguishes:

  • automated coverage, where repository tests exercise a real TCP, TLS, or WebSocket listener;
  • observed compatibility, where an unmodified client has been used against a Telex server; and
  • client-dependent presentation, where the server contract is implemented but a particular client may ignore or expose the underlying protocol.

The observations below are useful evidence, not a support guarantee for every version or platform.

Connection settings

For a typical deployment:

Field Value
Protocol IRC
Port 6697
TLS Required
SASL mechanism PLAIN over TLS
SASL username Human account name
SASL password Human account password

The optional IRC-over-WebSocket adapter carries the same IRC protocol and human SASL credentials. The reference web client normally reaches it through a same-origin /irc route.

Automation app keys are deliberately rejected by IRC SASL. A bot or agent uses its account/key-id and ak1… key against the HTTPS native/control gateway, commonly port 8098. See the automation examples.

Current matrix

Behavior Server coverage Existing-client expectation
CAP 302, registration, MOTD, JOIN, PART, NAMES, TOPIC, MODE, PING/PONG Automated Ordinary IRC clients
Human account authentication with SASL PLAIN over TLS Automated Clients with SASL support
Concurrent clients using one human account Automated Ordinary IRC clients
Reconnect, bounded legacy replay, and retained history Automated Ordinary clients receive the compatibility replay
Explicit CHATHISTORY, read markers, and installation delivery cursors Automated Requires negotiated extension support
Account tags, message tags, server time, batch, labeled responses Automated Requires the corresponding IRCv3 capability
Durable reactions Automated Unsupported clients receive no fallback spam
Client-only TAGMSG such as typing state Automated Relayed only to clients that negotiated message tags
Atomic multiline messages with legacy fallback Automated Capable clients receive one batch; legacy clients receive ordered lines
Message replies Automated Capable clients receive +reply; other clients see ordinary text
Invite, kick, voice/operator, bans, channel key, and user limit Automated Ordinary IRC controls
Account-stable direct messages Automated Ordinary nickname-directed messages map to account conversations
Provider catalogue and XDCC-compatible transfer flow Automated Client presentation varies

Irssi, WeeChat, HexChat, HexDroid, Textual, and mIRC have all been used during development for ordinary connection and chat paths. Their treatment of newer IRCv3 tags differs substantially. The reference web client exercises Telex's complete account, history, reaction, reply, avatar, and installation model.

Compatibility behavior

History and reconnect

Clients that do not negotiate explicit history or installation-resume extensions receive a bounded overlap when they join. A duplicate is preferable to a silent gap, but the fallback does not pretend to maintain a per-installation delivery checkpoint.

Clients implementing the native or documented resume path acknowledge only after durable local storage succeeds. Account-wide read state and per-installation delivery state remain separate.

Reactions and client-only tags

Telex never turns an unsupported reaction into a synthetic chat message. Clients that negotiate reaction and message-tag capabilities receive the structured event; others receive nothing. The same rule applies to typing and other client-only TAGMSG traffic.

Some clients display raw tags or status notices even when they do not render the feature. That is a client presentation issue rather than retained channel content: tag-only events are not stored in chat history.

Multiline

Telex accepts draft/multiline batches and stores them as one durable event. Negotiating clients receive the atomic batch. Legacy clients receive the lines in order without repeated sender metadata from the server; their own UI decides how much spacing to add.

Read markers

Read markers always resolve to a stored event. Telex tolerates a small amount of timestamp imprecision from clients while preserving a monotonic, event-backed cursor. Client-local status targets such as *server* are stateless and do not create retained messages.

Liveness

Registered TCP and WebSocket sessions receive ordinary IRC PING checks. Compatible clients answer with PONG automatically and usually hide both frames. Heartbeats never enter history or unread state.

Reporting a compatibility problem

Use a disposable account and remove secrets before sharing:

  • Telex revision and deployment topology relevant to the connection;
  • client name, version, operating system, and transport;
  • capabilities requested and acknowledged;
  • the smallest redacted protocol transcript that reproduces the behavior; and
  • whether the problem affects connection, retained data, or presentation only.

Do not post passwords, app keys, invitation tokens, installation tokens, content capabilities, private messages, production databases, or unredacted server logs.