`(sigil irc chathistory)`

(sigil irc chathistory) - CHATHISTORY command helpers (IRCv3 draft)

CHATHISTORY lets clients query history without disconnecting. The capability tag draft/chathistory advertises a chathistory=<MAX> integer for the server's per-query message limit.

Subcommands (per https://ircv3.net/specs/extensions/chathistory):

CHATHISTORY BEFORE <target> <selector> <limit>
CHATHISTORY AFTER  <target> <selector> <limit>
CHATHISTORY LATEST <target> <selector> <limit>
CHATHISTORY AROUND <target> <selector> <limit>
CHATHISTORY BETWEEN <target> <selector1> <selector2> <limit>
CHATHISTORY TARGETS <selector1> <selector2> <limit>

A selector is one of:

timestamp=<RFC-3339-UTC>
msgid=<msgid-string>
*                              (means "current" / endpoint)

Server responses are wrapped in a chathistory batch tagged with the target channel/nick (a single param after the type), and the messages within it carry their original msgid and time tags so the client can re-anchor its view.

Failures use the IRCv3 standard-replies format:

FAIL CHATHISTORY <error-code> <subcommand> [<params>...] :<text>

with <error-code> from a small enum: INVALIDPARAMS, INVALIDTARGET, MESSAGEERROR, NEEDMORE_PARAMS.

This module provides:

Subcommand and selector enumerated constants
A chathistory-query record + parser/serializer for the client→server line
Helpers to build the server's batch+messages response
Helpers to build the FAIL standard-reply

Exports

chathistory-selectorprocedure

Selectors identify positions in history. kind is one of:

'timestamp   value is an RFC 3339 UTC timestamp string
'msgid       value is a server-assigned msgid string
'star        value is #f (selector is `*`, meaning "now")

chathistory-selector?procedure

Test if a value is a chathistory-selector struct.

chathistory-selector-kindprocedure

Get the kind field of a chathistory-selector struct.

chathistory-selector-valueprocedure

Get the value field of a chathistory-selector struct.

parse-chathistory-selectorprocedure

Parse a single selector token. Returns a selector record on success or #f on malformed input.

chathistory-selector->stringprocedure

Serialize a selector back to its wire form.

%chathistory-query--typevariable

Serialize a selector back to its wire form.

chathistory-queryprocedure

A parsed CHATHISTORY query.

subcommand: string, one of CHATHISTORY-* constants target: string, channel or nick (#f for TARGETS subcommand) selector1: chathistory-selector selector2: chathistory-selector or #f (BETWEEN/TARGETS only) limit: integer

chathistory-query?procedure

Test if a value is a chathistory-query struct.

chathistory-query-subcommandprocedure

Get the subcommand field of a chathistory-query struct.

chathistory-query-targetprocedure

Get the target field of a chathistory-query struct.

chathistory-query-selector1procedure

Get the selector1 field of a chathistory-query struct.

chathistory-query-selector2procedure

Get the selector2 field of a chathistory-query struct.

chathistory-query-limitprocedure

Get the limit field of a chathistory-query struct.

parse-chathistory-lineprocedure

Parse an incoming CHATHISTORY message into a query record. Returns the query on success, or #f if malformed.

(parse-chathistory-line
  (parse-irc-message "CHATHISTORY BEFORE #chan timestamp=2026-04-27T12:00:00Z 50"))
; => #<chathistory-query subcommand: "BEFORE" target: "#chan"
;     selector1: #<sel timestamp> selector2: #f limit: 50>

chathistory-lineprocedure

Serialize a chathistory-query back to a wire-format CHATHISTORY line (with CRLF). Useful for client-side construction.

CHATHISTORY-BATCH-TYPEvariable

(No description)

CHATHISTORY-BEFOREvariable

(No description)

CHATHISTORY-AFTERvariable

(No description)

CHATHISTORY-LATESTvariable

(No description)

CHATHISTORY-AROUNDvariable

(No description)