yaic 0.1.0 → 0.2.0

data/docs/agents/data-model.md

@@ -0,0 +1,150 @@
+# YAIC Data Model
+
+This document describes the core data structures used in the YAIC IRC client library.
+
+## IRC Message Structure
+
+Every IRC message follows this format:
+```
+['@' <tags> SPACE] [':' <source> SPACE] <command> <parameters> <crlf>
+```
+
+### Message Class
+
+```ruby
+Yaic::Message
+  - tags: Hash[String, String]     # Optional IRCv3 message tags
+  - source: Yaic::Source or nil    # Origin of message (nil for client-sent)
+  - command: String                # Command name or 3-digit numeric
+  - params: Array[String]          # Command parameters (0-15+)
+  - raw: String                    # Original raw message (for debugging)
+```
+
+### Source Class
+
+Represents the origin of a message:
+```ruby
+Yaic::Source
+  - nick: String or nil      # Nickname (nil if server)
+  - user: String or nil      # Username (after !)
+  - host: String or nil      # Hostname (after @)
+  - raw: String              # Original source string
+```
+
+Formats:
+- `servername` - Message from server
+- `nick!user@host` - Full user prefix
+- `nick!user` - User without host
+- `nick@host` - User without username
+- `nick` - Just nickname
+
+## Connection State
+
+```ruby
+Yaic::Connection
+  - state: Symbol            # :disconnected, :connecting, :registering, :connected
+  - server: String           # Server hostname
+  - port: Integer            # Server port (default 6697)
+  - ssl: Boolean             # Use TLS/SSL
+  - nickname: String         # Current nickname
+  - username: String         # Username sent in USER
+  - realname: String         # Realname sent in USER
+  - password: String or nil  # Server password (optional)
+```
+
+### Connection States
+
+1. `:disconnected` - Not connected to server
+2. `:connecting` - TCP/TLS handshake in progress
+3. `:registering` - Sent NICK/USER, awaiting welcome
+4. `:connected` - Registered and ready for commands
+
+## Channel State
+
+```ruby
+Yaic::Channel
+  - name: String             # Channel name (e.g., "#ruby")
+  - topic: String or nil     # Channel topic
+  - topic_setter: String     # Who set the topic
+  - topic_time: Time         # When topic was set
+  - users: Hash[String, Set[Symbol]]  # nick => set of modes (@, +, etc.)
+  - modes: Hash[Symbol, Object]       # Channel modes
+```
+
+## User State
+
+```ruby
+Yaic::User
+  - nick: String
+  - user: String or nil
+  - host: String or nil
+  - realname: String or nil
+  - away: Boolean
+  - away_message: String or nil
+```
+
+## Event Types
+
+Events emitted by the client:
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `:connect` | `{server:}` | Successfully connected and registered |
+| `:disconnect` | `{reason:}` | Connection closed |
+| `:message` | `{source:, target:, text:}` | PRIVMSG received |
+| `:notice` | `{source:, target:, text:}` | NOTICE received |
+| `:join` | `{channel:, user:}` | User joined channel |
+| `:part` | `{channel:, user:, reason:}` | User left channel |
+| `:quit` | `{user:, reason:}` | User quit IRC |
+| `:kick` | `{channel:, user:, by:, reason:}` | User kicked from channel |
+| `:nick` | `{old_nick:, new_nick:}` | User changed nickname |
+| `:topic` | `{channel:, topic:, setter:}` | Topic changed |
+| `:mode` | `{target:, modes:, args:}` | Mode changed |
+| `:raw` | `{message:}` | Any raw message (for debugging) |
+| `:error` | `{numeric:, message:}` | Error from server |
+
+## Message Length Limits
+
+- Base message: 512 bytes (including CRLF)
+- With IRCv3 tags: 512 + 8191 = 8703 bytes max
+- Usable content: 510 bytes (excluding CRLF)
+
+## Character Encoding
+
+- Primary: UTF-8
+- Fallback: Latin-1 (ISO-8859-1)
+- Invalid bytes: Replace with replacement character
+
+## Nickname Restrictions
+
+Must NOT contain:
+- SPACE (0x20)
+- Comma (0x2C)
+- Asterisk (0x2A)
+- Question mark (0x3F)
+- Exclamation mark (0x21)
+- At sign (0x40)
+
+Must NOT start with:
+- Dollar (0x24)
+- Colon (0x3A)
+- Channel prefix (#, &)
+
+## Channel Name Restrictions
+
+Must start with:
+- `#` (regular channel)
+- `&` (local channel)
+
+Must NOT contain:
+- SPACE (0x20)
+- BELL (0x07)
+- Comma (0x2C)
+
+## Numeric Reply Categories
+
+| Range | Category |
+|-------|----------|
+| 001-099 | Connection/welcome |
+| 200-399 | Command responses |
+| 400-599 | Error responses |

data/docs/agents/ralph/features/01-message-parsing.md.done

@@ -0,0 +1,160 @@
+# Message Parsing
+
+## Description
+
+Implement the core message parsing and serialization module that converts between raw IRC protocol bytes and structured Ruby objects. This is the foundation upon which all other IRC functionality is built.
+
+## Behavior
+
+### Parsing Incoming Messages
+
+Parse raw IRC messages in the format:
+```
+['@' <tags> SPACE] [':' <source> SPACE] <command> <parameters> <crlf>
+```
+
+Components are parsed in order:
+1. If starts with `@`, extract tags until first SPACE
+2. If starts with `:`, extract source until first SPACE
+3. Extract command (letters or 3-digit numeric)
+4. Extract parameters (space-separated, last may have `:` prefix for trailing)
+
+### Serializing Outgoing Messages
+
+Convert `Yaic::Message` objects to wire format:
+- NEVER include source (clients don't send source)
+- Append `\r\n` to every message
+- Prepend `:` to trailing parameter if it contains spaces, is empty, or starts with `:`
+
+### Tag Parsing
+
+Tags format: `@key1=value1;key2=value2`
+- Split on `;`
+- Split each on `=` for key/value
+- Value may be empty
+- Strip leading `@`
+
+### Source Parsing
+
+Parse formats:
+- `servername`
+- `nick!user@host`
+- `nick!user`
+- `nick@host`
+- `nick`
+
+### Parameter Parsing
+
+- Split on SPACE
+- Last parameter with `:` prefix is "trailing" - can contain spaces
+- Strip the `:` prefix from trailing parameter
+
+## Models
+
+See `docs/agents/data-model.md` for:
+- `Yaic::Message` structure
+- `Yaic::Source` structure
+
+## Tests
+
+### Unit Tests - Message Parsing
+
+**Parse simple command**
+- Given: `"PING :token123\r\n"`
+- When: Parse message
+- Then: command = "PING", params = ["token123"]
+
+**Parse message with source**
+- Given: `":nick!user@host PRIVMSG #channel :Hello world\r\n"`
+- When: Parse message
+- Then: source.nick = "nick", source.user = "user", source.host = "host", command = "PRIVMSG", params = ["#channel", "Hello world"]
+
+**Parse message with tags**
+- Given: `"@id=123;time=2023-01-01 :server NOTICE * :Hello\r\n"`
+- When: Parse message
+- Then: tags = {"id" => "123", "time" => "2023-01-01"}, source.raw = "server"
+
+**Parse numeric reply**
+- Given: `":irc.example.com 001 mynick :Welcome\r\n"`
+- When: Parse message
+- Then: command = "001", params = ["mynick", "Welcome"]
+
+**Parse message with empty trailing**
+- Given: `":server CAP * LIST :\r\n"`
+- When: Parse message
+- Then: params = ["*", "LIST", ""]
+
+**Parse message with colon in trailing**
+- Given: `":nick PRIVMSG #chan ::-)\r\n"`
+- When: Parse message
+- Then: params = ["#chan", ":-)"]
+
+**Parse message without trailing colon**
+- Given: `"NICK newnick\r\n"`
+- When: Parse message
+- Then: command = "NICK", params = ["newnick"]
+
+**Parse source - server only**
+- Given: source string "irc.example.com"
+- When: Parse source
+- Then: nick = nil, host = "irc.example.com"
+
+**Parse source - full user**
+- Given: source string "dan!~d@localhost"
+- When: Parse source
+- Then: nick = "dan", user = "~d", host = "localhost"
+
+**Parse source - nick only**
+- Given: source string "dan"
+- When: Parse source
+- Then: nick = "dan", user = nil, host = nil
+
+### Unit Tests - Message Serialization
+
+**Serialize simple command**
+- Given: Message with command = "NICK", params = ["mynick"]
+- When: Serialize
+- Then: Output = "NICK mynick\r\n"
+
+**Serialize with trailing spaces**
+- Given: Message with command = "PRIVMSG", params = ["#chan", "Hello world"]
+- When: Serialize
+- Then: Output = "PRIVMSG #chan :Hello world\r\n"
+
+**Serialize with empty trailing**
+- Given: Message with command = "TOPIC", params = ["#chan", ""]
+- When: Serialize
+- Then: Output = "TOPIC #chan :\r\n"
+
+**Never include source in client messages**
+- Given: Message with source set, command = "NICK", params = ["test"]
+- When: Serialize
+- Then: Output = "NICK test\r\n" (no source)
+
+### Edge Cases
+
+**Handle LF-only line endings from server**
+- Given: `"PING :test\n"`
+- When: Parse message
+- Then: Successfully parses (compatibility mode)
+
+**Ignore empty lines**
+- Given: `"\r\n"`
+- When: Parse message
+- Then: Return nil or skip
+
+**Handle multiple spaces between components**
+- Given: `":server  PRIVMSG  #chan  :text\r\n"` (extra spaces)
+- When: Parse message
+- Then: Successfully parses
+
+## Implementation Notes
+
+- Use a Message class with `parse` class method and `to_s` instance method
+- Source should be a separate class with parsing logic
+- Consider using StringScanner for efficient parsing
+- UTF-8 encoding by default, with fallback to Latin-1
+
+## Dependencies
+
+None - this is the foundation feature.

data/docs/agents/ralph/features/01-tcpsocket-refactor.md.done

@@ -0,0 +1,109 @@
+# TCPSocket Refactor
+
+## Description
+
+Replace the low-level `::Socket` usage in `lib/yaic/socket.rb` with Ruby's higher-level `TCPSocket` class. The current implementation uses `::Socket.new` with manual address resolution and nonblocking connect patterns. `TCPSocket` provides a simpler, more readable interface while still supporting the same functionality.
+
+## Behavior
+
+### Current Implementation
+
+The current socket uses:
+- `::Socket.new(afamily, SOCK_STREAM)` - low-level socket creation
+- `Addrinfo.getaddrinfo` - manual DNS resolution with IPv4 preference
+- `connect_nonblock` with `IO.select` timeout handling
+- `setsockopt` for TCP keepalive
+
+### Target Implementation
+
+Replace with `TCPSocket` which:
+- Handles address resolution internally
+- Provides cleaner connection semantics with built-in timeout support
+- Maintains SSL wrapping compatibility
+
+### Changes Required
+
+1. **Remove `resolve_address` method** - `TCPSocket.new` handles DNS resolution
+2. **Replace `::Socket.new` with `TCPSocket.new`** in the `connect` method
+3. **Use `connect_timeout` parameter** - `TCPSocket.new(host, port, connect_timeout: timeout)` (Ruby 3.0+)
+4. **Remove nonblocking connect logic** - no more `connect_nonblock`, `IO.select`, or `IO::WaitWritable` handling
+5. **Preserve keepalive** - Use `setsockopt` on the returned TCPSocket
+6. **SSL wrapping remains unchanged** - `wrap_ssl` works with any socket-like object
+
+### Connection Flow (After)
+
+```ruby
+def connect
+  tcp_socket = TCPSocket.new(@host, @port, connect_timeout: @connect_timeout)
+  tcp_socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+
+  @socket = @ssl ? wrap_ssl(tcp_socket) : tcp_socket
+  @state = :connecting
+end
+```
+
+### Error Handling
+
+- `Errno::ETIMEDOUT` - connection timeout (behavior unchanged)
+- `Errno::ECONNREFUSED` - server not listening (behavior unchanged)
+- `SocketError` - DNS resolution failure (new, replaces custom handling)
+
+## Models
+
+No database models involved. This is a refactor of the `Yaic::Socket` class.
+
+## Tests
+
+### Unit Tests
+
+The existing unit tests in `test/socket_test.rb` test private buffer methods via `send()`. These do not need modification as they don't test connection logic.
+
+### Integration Tests
+
+Update `test/integration/socket_test.rb` to verify the refactored implementation:
+
+**Connection to running server**
+- Given: IRC server running on localhost:6667
+- When: `Socket.new("localhost", 6667).connect`
+- Then: Socket state is `:connecting`, socket is usable
+
+**Connection with SSL**
+- Given: IRC server running with SSL on localhost:6697
+- When: `Socket.new("localhost", 6697, ssl: true).connect`
+- Then: Socket state is `:connecting`, SSL handshake completed
+
+**Connection timeout**
+- Given: Non-routable IP like 10.255.255.1
+- When: `Socket.new("10.255.255.1", 6667, connect_timeout: 1).connect`
+- Then: Raises `Errno::ETIMEDOUT` within ~1 second
+
+**Connection refused**
+- Given: No server running on localhost:59999
+- When: `Socket.new("localhost", 59999).connect`
+- Then: Raises `Errno::ECONNREFUSED`
+
+**DNS resolution failure**
+- Given: Non-existent hostname
+- When: `Socket.new("this.host.does.not.exist.invalid", 6667).connect`
+- Then: Raises `SocketError` with DNS-related message
+
+**Keepalive option set**
+- Given: Server running
+- When: Connect and inspect socket options
+- Then: `SO_KEEPALIVE` option is enabled on the underlying socket
+
+**Read/write still work after refactor**
+- Given: Connected socket
+- When: Write a message and read response
+- Then: Nonblocking I/O behavior unchanged
+
+## Implementation Notes
+
+- Ruby 3.0+ only - uses `connect_timeout` parameter
+- The `TCPSocket` class is in the `socket` library, already required
+- `TCPSocket` is a subclass of `IPSocket` which is a subclass of `BasicSocket`, so all socket methods remain available
+- IPv4 preference logic in `resolve_address` will be lost - `TCPSocket` uses system resolver order. This is acceptable for modern dual-stack systems.
+
+## Dependencies
+
+None - this is a standalone refactoring task.

data/docs/agents/ralph/features/02-connection-socket.md.done

@@ -0,0 +1,138 @@
+# Connection Socket
+
+## Description
+
+Implement the low-level TCP/SSL socket connection handling. This provides the transport layer for sending and receiving raw IRC messages.
+
+## Behavior
+
+### Connecting
+
+1. Create TCP socket to server:port
+2. If SSL enabled, wrap in OpenSSL::SSL::SSLSocket
+3. Set socket to non-blocking mode for read operations
+4. Transition state to `:connecting` then `:registering`
+
+### Reading
+
+- Read from socket into internal buffer
+- Extract complete messages (ending in `\r\n`)
+- Handle partial messages (keep in buffer until complete)
+- Accept `\n` alone as line ending for compatibility
+
+### Writing
+
+- Queue outgoing messages
+- Append `\r\n` if not present
+- Write to socket
+- Handle write blocking (rare but possible)
+
+### Disconnecting
+
+- Close socket gracefully
+- Clear buffers
+- Transition state to `:disconnected`
+
+### Error Handling
+
+- Handle connection refused
+- Handle connection timeout
+- Handle SSL handshake failures
+- Handle socket read/write errors
+
+## Models
+
+```ruby
+Yaic::Socket
+  - socket: TCPSocket or SSLSocket
+  - read_buffer: String
+  - write_queue: Array[String]
+  - state: Symbol
+```
+
+## Tests
+
+### Integration Tests - Plain TCP
+
+**Connect to server**
+- Given: inspircd running on localhost:6667 (no SSL)
+- When: Connect with ssl: false
+- Then: Socket is connected, state is :connecting
+
+**Read complete message**
+- Given: Connected socket, server sends "PING :test\r\n"
+- When: Read from socket
+- Then: Returns "PING :test\r\n"
+
+**Read partial then complete**
+- Given: Connected socket
+- When: Server sends "PING :" then ":test\r\n" in separate packets
+- Then: First read returns nil, second read returns complete message
+
+**Write message**
+- Given: Connected socket
+- When: Write "PONG :test"
+- Then: Server receives "PONG :test\r\n"
+
+**Disconnect**
+- Given: Connected socket
+- When: Disconnect
+- Then: Socket is closed, state is :disconnected
+
+### Integration Tests - SSL
+
+**Connect with SSL**
+- Given: inspircd running on localhost:6697 (SSL)
+- When: Connect with ssl: true
+- Then: Socket is connected via TLS
+
+**SSL handshake failure**
+- Given: Server with invalid/self-signed cert
+- When: Connect with ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER
+- Then: Raises SSLError or similar
+
+### Unit Tests - Buffer Handling
+
+**Buffer accumulates partial messages**
+- Given: Empty buffer
+- When: Receive "PING" then " :test" then "\r\n"
+- Then: After third receive, extract "PING :test\r\n"
+
+**Multiple messages in one read**
+- Given: Empty buffer
+- When: Receive "MSG1\r\nMSG2\r\n"
+- Then: Extract returns ["MSG1\r\n", "MSG2\r\n"]
+
+**Handle LF-only endings**
+- Given: Empty buffer
+- When: Receive "PING :test\n"
+- Then: Extract returns "PING :test\n"
+
+### Error Handling Tests
+
+**Connection refused**
+- Given: No server on target port
+- When: Attempt connect
+- Then: Raises connection error
+
+**Connection timeout**
+- Given: Server that doesn't respond
+- When: Connect with timeout
+- Then: Raises timeout error after specified time
+
+**Read on closed socket**
+- Given: Socket that was closed by server
+- When: Attempt read
+- Then: Returns nil or raises appropriate error
+
+## Implementation Notes
+
+- Use Ruby's `TCPSocket` and `OpenSSL::SSL::SSLSocket`
+- Set `sync = true` on SSL socket for unbuffered writes
+- Consider using `IO.select` for non-blocking reads
+- Buffer should be a binary string (encoding: ASCII-8BIT)
+- Implement reconnection logic in higher layer, not here
+
+## Dependencies
+
+- Requires `01-message-parsing.md` for message framing knowledge