README
¶
irc
Documentation
¶
Overview ¶
Package irc provides a high-level, event-driven IRCv3 client that manages connection, registration, capability negotiation, and reconnection.
Index ¶
- Variables
- type BackoffPolicy
- type BatchEvent
- type CTCPEvent
- type CapNegotiatedEvent
- type ChathistoryEvent
- type Client
- func (c *Client) Action(target, text string) error
- func (c *Client) Caps() []string
- func (c *Client) Channel(name string) (ircstate.ChannelView, bool)
- func (c *Client) Channels() []ircstate.ChannelView
- func (c *Client) Close(ctx context.Context, quitMsg string) error
- func (c *Client) Connect(ctx context.Context) error
- func (c *Client) Connected() bool
- func (c *Client) Dropped() uint64
- func (c *Client) Events() <-chan Event
- func (c *Client) HasCap(name string) bool
- func (c *Client) ISupport() ircsupport.ISupportView
- func (c *Client) Join(channels ...string) error
- func (c *Client) LastMsgID(target string) string
- func (c *Client) MarkRead(target string, when time.Time) error
- func (c *Client) MonitorAdd(nicks ...string) error
- func (c *Client) MonitorClear() error
- func (c *Client) MonitorList() ([]string, error)
- func (c *Client) MonitorRemove(nicks ...string) error
- func (c *Client) Notice(target, text string) error
- func (c *Client) On(kind EventKind, fn HandlerFunc) Unsubscribe
- func (c *Client) OnRaw(command string, fn RawHandlerFunc) Unsubscribe
- func (c *Client) Part(channel, reason string) error
- func (c *Client) Privmsg(target, text string) error
- func (c *Client) QueryReadMarker(target string) error
- func (c *Client) Quit(message string) error
- func (c *Client) RequestHistory(target string, op HistoryOp, ref HistoryRef, limit int) error
- func (c *Client) RequestHistoryRange(target string, r HistoryRange, limit int) error
- func (c *Client) Run(ctx context.Context) error
- func (c *Client) Self() string
- func (c *Client) Send(m ircmsg.Message) error
- func (c *Client) SendCTCP(target, command, args string) error
- func (c *Client) SendLabeled(ctx context.Context, m ircmsg.Message) (Response, error)
- func (c *Client) SendMultiline(target, text string) error
- func (c *Client) SetNick(nick string) error
- func (c *Client) Subscribe(opts SubOptions) (<-chan Event, Unsubscribe)
- func (c *Client) User(nick string) (ircstate.UserView, bool)
- func (c *Client) WhoX(target string) error
- type Config
- type CredentialSource
- type DisconnectedEvent
- type Event
- type EventKind
- type ExponentialBackoff
- type GapEvent
- type HandlerFunc
- type Hint
- type HistoryOp
- type HistoryRange
- type HistoryRef
- type InviteEvent
- type JoinEvent
- type KickEvent
- type MarkReadEvent
- type MarkReadSource
- type MessageEvent
- type MessageRef
- type ModeChangeEvent
- type MonitorEvent
- type NickChangeEvent
- type OverflowPolicy
- type PartEvent
- type QuitEvent
- type RawEvent
- type RawHandlerFunc
- type RegisteredEvent
- type Resolved
- type Response
- type ResubscribedEvent
- type SASLConfig
- type StandardReplyEvent
- type SubOptions
- type TopicEvent
- type Unsubscribe
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidConfig indicates the Config failed validation. ErrInvalidConfig = errors.New("irc: invalid config") // ErrCapsTimeout indicates capability negotiation did not complete in time. ErrCapsTimeout = errors.New("irc: capability negotiation timed out") // ErrRegistrationTimeout indicates registration did not complete in time. ErrRegistrationTimeout = errors.New("irc: registration timed out") // ErrDisconnected indicates the connection was lost. ErrDisconnected = errors.New("irc: disconnected") // ErrNotConnected indicates an operation was attempted before connecting. ErrNotConnected = errors.New("irc: not connected") // ErrClosed indicates the connection was closed by the caller. ErrClosed = errors.New("irc: closed by caller") // ErrSTSUpgrade indicates an STS upgrade is required and a TLS retry follows. ErrSTSUpgrade = errors.New("irc: STS upgrade required; retrying over TLS") // ErrLabelMismatch indicates a labeled response did not match its request. ErrLabelMismatch = errors.New("irc: labeled-response mismatch") )
Errors returned by the client.
Functions ¶
This section is empty.
Types ¶
type BackoffPolicy ¶
BackoffPolicy reports the delay before reconnect attempt n, where n is 0 on the first failure and increments per consecutive failure.
type BatchEvent ¶
BatchEvent reports the completion of a batch whose lines were dispatched live.
type CTCPEvent ¶
type CTCPEvent struct {
From ircmsg.NickUserHost
Target string
Command string
Args string
IsReply bool
// contains filtered or unexported fields
}
CTCPEvent reports a CTCP request or reply.
type CapNegotiatedEvent ¶
type CapNegotiatedEvent struct {
Acked []string
// contains filtered or unexported fields
}
CapNegotiatedEvent reports that capability negotiation finished, listing the acknowledged capabilities.
type ChathistoryEvent ¶
type ChathistoryEvent struct {
Target string
Messages []MessageEvent
// Complete reports whether the history is exhausted; if false, more is
// available via an earlier BEFORE request.
Complete bool
// contains filtered or unexported fields
}
ChathistoryEvent reports a completed chat-history batch for a target.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the high-level handle to an IRC connection. Drive it from one place: Connect and Run are not goroutine-safe with each other.
func New ¶
New returns a Client for the given configuration. It never fails; required-field validation is deferred to Connect, and Send or Close calls before the first Connect return ErrNotConnected rather than blocking.
func (*Client) Channel ¶
func (c *Client) Channel(name string) (ircstate.ChannelView, bool)
Channel returns a view of the named channel and reports whether it was found.
func (*Client) Channels ¶
func (c *Client) Channels() []ircstate.ChannelView
Channels returns views of all channels the client is currently joined to.
func (*Client) Connect ¶
Connect dials the server and completes capability negotiation and registration, returning once the connection is registered or an error.
func (*Client) Connected ¶
Connected reports whether the client has an active, registered connection.
func (*Client) Dropped ¶
Dropped returns the number of events dropped on the Events stream because the subscriber could not keep up.
func (*Client) ISupport ¶
func (c *Client) ISupport() ircsupport.ISupportView
ISupport returns a view of the server's ISUPPORT parameters.
func (*Client) MarkRead ¶
MarkRead tells the server the client has read target up to the given time. It returns an error if the read-marker capability is unsupported.
func (*Client) MonitorAdd ¶
MonitorAdd adds nicks to the server's monitor list, chunked to respect the advertised limit. It returns errMonitorUnsupported if MONITOR is unavailable.
func (*Client) MonitorClear ¶
MonitorClear clears the entire monitor list, locally and on the server.
func (*Client) MonitorList ¶
MonitorList returns the locally-tracked watch list (display forms). No network round-trip; the error is reserved for a future MONITOR L sync.
func (*Client) MonitorRemove ¶
MonitorRemove removes nicks from the server's monitor list.
func (*Client) On ¶
func (c *Client) On(kind EventKind, fn HandlerFunc) Unsubscribe
On registers fn to handle events of the given kind and returns a function to cancel the subscription.
func (*Client) OnRaw ¶
func (c *Client) OnRaw(command string, fn RawHandlerFunc) Unsubscribe
OnRaw registers fn to handle raw messages with the given command ("*" for all) and returns a function to cancel the subscription.
func (*Client) Part ¶
Part leaves channel with an optional reason and drops it from the reconnect plan.
func (*Client) QueryReadMarker ¶
QueryReadMarker asks the server for target's current read marker. It returns an error if the read-marker capability is unsupported.
func (*Client) Quit ¶
Quit closes the connection and stops reconnection. QUIT rides the priority lane so it can't wait out the server's quit grace behind a throttled outbox.
func (*Client) RequestHistory ¶
RequestHistory requests up to limit messages of target's history for the given operation, anchored at ref. It returns an error if chathistory is unsupported.
func (*Client) RequestHistoryRange ¶
func (c *Client) RequestHistoryRange(target string, r HistoryRange, limit int) error
RequestHistoryRange requests up to limit messages of target's history within the range r. It returns an error if chathistory is unsupported.
func (*Client) Run ¶
Run connects and, when AutoReconnect is set, reconnects with backoff until ctx is cancelled or a non-recoverable error occurs.
func (*Client) SendCTCP ¶
SendCTCP sends a CTCP request of the given command and arguments to the target.
func (*Client) SendLabeled ¶
SendLabeled sends m with a label tag and waits for the server's labeled reply (a single line, or a labeled-response batch's inner lines).
func (*Client) SendMultiline ¶
SendMultiline sends text, which may contain newlines, to target as one logical message, using a draft/multiline batch when negotiated and otherwise falling back to one PRIVMSG per line.
func (*Client) SetNick ¶
SetNick changes the client's nickname and records it as the desired nick for replay after a reconnect.
func (*Client) Subscribe ¶
func (c *Client) Subscribe(opts SubOptions) (<-chan Event, Unsubscribe)
Subscribe registers a new subscription with the given options and returns its event channel and a function to cancel it.
type Config ¶
type Config struct {
Nick, User, Realname string
AltNicks []string
Server string
// Dialer establishes the connection; nil selects the default TCPDialer.
Dialer ircconn.Dialer
// TLS configures a TLS connection; nil selects plaintext.
TLS *tls.Config
ServerPassword string
SASL SASLConfig
Credentials CredentialSource
// AutoReplies configures CTCP auto-replies; the zero value disables all.
AutoReplies ircctcp.AutoReplies
// STSStore persists STS policy; nil disables STS.
STSStore ircsts.Store
DesiredCaps []string
// CapsFilter receives the advertised caps and the computed desired set; its
// return replaces desired, re-intersected with advertised.
CapsFilter func(advertised map[string]string, desired []string) []string
AutoReconnect bool
Backoff BackoffPolicy
// StabilityWindow is the minimum uptime to reset backoff; 0 selects 60s.
StabilityWindow time.Duration
MaxLineLen int
// SendQueueDepth is the outbox depth; 0 selects 64.
SendQueueDepth int
// HandlerMailbox is the per-subscriber mailbox depth; 0 selects 256.
HandlerMailbox int
SendRate ircconn.RateLimit
// KeepAlive is the idle interval before a keepalive probe; 0 selects 120s
// and a negative value disables keepalive.
KeepAlive time.Duration
// KeepAliveTimeout is the wait for a keepalive response; 0 selects 30s.
KeepAliveTimeout time.Duration
// RegisterTimeout is the dial-to-001 budget; 0 selects 60s.
RegisterTimeout time.Duration
Logger *slog.Logger
}
Config holds the parameters for constructing a Client. The zero value is not usable; at minimum Server and Nick must be set.
type CredentialSource ¶
type CredentialSource interface {
Resolve(ctx context.Context, network string, hint Hint) (Resolved, error)
}
CredentialSource resolves secrets at connect time, once per Connect.
type DisconnectedEvent ¶
type DisconnectedEvent struct {
Reason error
// contains filtered or unexported fields
}
DisconnectedEvent reports that the connection was lost, carrying the cause.
type Event ¶
Event is the common interface implemented by every event the client emits. Tags returns the original, shared, read-only tag map; copy it before modifying.
type EventKind ¶
type EventKind uint8
EventKind identifies the concrete type of an Event.
const ( EventMessage EventKind = iota + 1 EventCTCP EventJoin EventPart EventQuit EventKick EventNickChange EventModeChange EventTopic EventInvite EventRegistered EventCapNegotiated EventDisconnected EventResubscribed EventBatch EventChathistory EventMarkRead EventMonitor EventStandardReply EventGap EventRaw )
Event kinds reported by Kind.
type ExponentialBackoff ¶
ExponentialBackoff is the default policy: 2s·2ⁿ capped at Max, scaled by a uniform jitter factor in [1−Jitter, 1+Jitter].
type GapEvent ¶
type GapEvent struct {
Dropped uint64
Policy OverflowPolicy
// contains filtered or unexported fields
}
GapEvent reports that this subscription dropped events under overflow. The tracker stays authoritative; re-read snapshots for any mirrored state.
type HandlerFunc ¶
HandlerFunc handles a delivered Event.
type HistoryRange ¶
type HistoryRange struct {
From, To HistoryRef
}
HistoryRange bounds a history query between two references.
type HistoryRef ¶
type HistoryRef struct {
MsgID string
Timestamp time.Time
// Star, when set, selects the tail of history ("*") for a LATEST query.
Star bool
}
HistoryRef identifies a point in a target's history by message id or timestamp.
type InviteEvent ¶
type InviteEvent struct {
From ircmsg.NickUserHost
Channel string
// contains filtered or unexported fields
}
InviteEvent reports that the client was invited to a channel.
type JoinEvent ¶
type JoinEvent struct {
User ircmsg.NickUserHost
Account string
Channel string
Realname string
// contains filtered or unexported fields
}
JoinEvent reports that a user joined a channel.
type KickEvent ¶
type KickEvent struct {
By ircmsg.NickUserHost
Channel string
Kicked string
Reason string
// contains filtered or unexported fields
}
KickEvent reports that a user was kicked from a channel.
type MarkReadEvent ¶
type MarkReadEvent struct {
Target string
When time.Time
Source MarkReadSource
// contains filtered or unexported fields
}
MarkReadEvent reports a read-marker update for a target.
type MarkReadSource ¶
type MarkReadSource uint8
MarkReadSource identifies why a MarkReadEvent was emitted.
const ( // MarkReadSourceUnknown is the zero value, used when the source is unset. MarkReadSourceUnknown MarkReadSource = iota // MarkReadSourceSetAck acknowledges the client's own MarkRead (SET). MarkReadSourceSetAck // MarkReadSourceGetReply answers the client's QueryReadMarker (GET). MarkReadSourceGetReply // MarkReadSourcePush reports a read marker set by another device. MarkReadSourcePush )
Sources of a MarkReadEvent.
type MessageEvent ¶
type MessageEvent struct {
From ircmsg.NickUserHost
Account string
Target string
Text string
IsNotice bool
MsgID string
IsEcho bool
Reply *MessageRef
// contains filtered or unexported fields
}
MessageEvent reports a PRIVMSG or NOTICE.
type MessageRef ¶
type MessageRef struct {
MsgID string
}
MessageRef identifies a referenced message, such as a +draft/reply target.
type ModeChangeEvent ¶
type ModeChangeEvent struct {
By ircmsg.NickUserHost
Target string
Changes []ircsupport.ModeChange
// contains filtered or unexported fields
}
ModeChangeEvent reports a mode change on a channel or user.
type MonitorEvent ¶
type MonitorEvent struct {
Nick string
Online bool
// ListFull reports that the monitor list was full, so the watch was not added.
ListFull bool
// contains filtered or unexported fields
}
MonitorEvent reports a change in a monitored nick's online status.
type NickChangeEvent ¶
type NickChangeEvent struct {
User ircmsg.NickUserHost
Old string
New string
// contains filtered or unexported fields
}
NickChangeEvent reports that a user changed nicknames.
type OverflowPolicy ¶
type OverflowPolicy uint8
OverflowPolicy controls a subscription's behaviour when its mailbox is full. The tracker stays authoritative regardless, so a dropped event is recoverable by re-reading snapshots on the next GapEvent.
const ( // DropOldest evicts the oldest queued event to make room (the default). DropOldest OverflowPolicy = iota // DropNewest refuses the incoming event. DropNewest // Block back-pressures the dispatcher and never drops events. Block )
type PartEvent ¶
type PartEvent struct {
User ircmsg.NickUserHost
Channel string
Reason string
// contains filtered or unexported fields
}
PartEvent reports that a user left a channel.
type QuitEvent ¶
type QuitEvent struct {
User ircmsg.NickUserHost
Reason string
// contains filtered or unexported fields
}
QuitEvent reports that a user disconnected from the server.
type RawHandlerFunc ¶
RawHandlerFunc handles a raw protocol message.
type RegisteredEvent ¶
type RegisteredEvent struct {
// contains filtered or unexported fields
}
RegisteredEvent reports that registration with the server completed.
type Response ¶
type Response struct {
Messages []ircmsg.Message
// Batch is the batch type when the reply was batched, or "" otherwise.
Batch string
}
Response holds every line the server attributed to a SendLabeled request's label.
type ResubscribedEvent ¶
type ResubscribedEvent struct {
Channels []string
// contains filtered or unexported fields
}
ResubscribedEvent reports that the session plan was re-asserted after a reconnect, listing the rejoined channels.
type SASLConfig ¶
type SASLConfig struct {
// NewMech returns a fresh Mechanism per attempt, since mechanisms are
// stateful; returning nil aborts the attempt.
NewMech func() ircsasl.Mechanism
// Optional, when true, continues registration if the mechanism is
// unsupported rather than failing.
Optional bool
}
SASLConfig configures SASL authentication.
type StandardReplyEvent ¶
type StandardReplyEvent struct {
// Severity is one of "FAIL", "WARN", or "NOTE".
Severity string
Command string
Code string
Context []string
Text string
// contains filtered or unexported fields
}
StandardReplyEvent reports a standard-replies FAIL, WARN, or NOTE message.
type SubOptions ¶
type SubOptions struct {
// Kinds limits delivery to these event kinds; nil or empty means all kinds.
Kinds []EventKind
// Mailbox is the buffer size; 0 uses Config.HandlerMailbox.
Mailbox int
Overflow OverflowPolicy
}
SubOptions configures a subscription created with Subscribe.
type TopicEvent ¶
type TopicEvent struct {
By ircmsg.NickUserHost
Channel string
Topic string
// contains filtered or unexported fields
}
TopicEvent reports that a channel topic was changed.
type Unsubscribe ¶
type Unsubscribe func()
Unsubscribe cancels a subscription registered with On, OnRaw, or Subscribe.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ircconn provides transport connections that frame IRC messages, along with outbound rate limiting.
|
Package ircconn provides transport connections that frame IRC messages, along with outbound rate limiting. |
|
Package ircctcp encodes and decodes CTCP payloads and provides optional auto-replies to CTCP queries.
|
Package ircctcp encodes and decodes CTCP payloads and provides optional auto-replies to CTCP queries. |
|
Package ircmsg parses and serializes IRC protocol messages, including IRCv3 message tags.
|
Package ircmsg parses and serializes IRC protocol messages, including IRCv3 message tags. |
|
Package ircsasl provides pluggable SASL mechanisms for IRC authentication.
|
Package ircsasl provides pluggable SASL mechanisms for IRC authentication. |
|
Package ircstate maintains channel, user, and mode state for one connection from the parsed message stream, exposing value snapshots.
|
Package ircstate maintains channel, user, and mode state for one connection from the parsed message stream, exposing value snapshots. |
|
Package ircsts implements storage for IRCv3 Strict Transport Security policies.
|
Package ircsts implements storage for IRCv3 Strict Transport Security policies. |
|
Package ircsupport parses and stores the negotiated IRC 005 RPL_ISUPPORT tokens and exposes server-dependent helpers derived from them.
|
Package ircsupport parses and stores the negotiated IRC 005 RPL_ISUPPORT tokens and exposes server-dependent helpers derived from them. |
|
casemap
Package casemap folds nicks and channel names to a canonical form per the negotiated CASEMAPPING token so that case-insensitive comparison works.
|
Package casemap folds nicks and channel names to a canonical form per the negotiated CASEMAPPING token so that case-insensitive comparison works. |
|
Package testirc provides a scriptable in-process IRC server for integration tests.
|
Package testirc provides a scriptable in-process IRC server for integration tests. |