ObsidianIRC polls spec
ObsidianIRC Polls Specification
Overview
This document specifies the vendored capabilities, message formats, and implementation guidelines for integrated polling within ObsidianIRC, utilizing the IRCv3 standard, extended with client message-tags and metadata. The core capabilitiy introduced is through the IRCv3 capabilities mechanism, specifically with the 'obsidian/polls' cap.
1. Extension Capabilities
1.1 obsidian/polls Cap
This capability, when enabled by the server, indicates support for in-channel and private polls. Clients can negotiate this capability during the CAP LS exchange.
1.2 Negotiation
Clients and servers negotiate the obsidian/polls capability via the CAP negotiation mechanism. If supported by both, the client will activate poll-related message formats and metadata, which enable rich polling interactions.
2. Message Formats
2.1 Initiating a Poll
Clients initiate a poll using a PRIVMSG with specific message-tags and metadata. Example:
TAGs:
- event=pollstart
- id=<pollid>
- question=<UTF-8 string>
- options=<list of options>
- anonymous=<true/false (optional)>
Message format:
@event=pollstart;id=1234;question=What is your favorite color?;options=Red,Blue,Green;anonymous=false :<target> !poll
2.2 Voting
Users submit votes similarly, with message-tags indicating vote event:
TAGs:
- event=pollvote
- id=<pollid>
- option=<optionvalue>
Message format:
@event=pollvote;id=1234;option=Blue :<target> !vote
2.3 Ending or Closing a Poll
Polls can be ended either by the poll creator or by server policy:
TAGs:
- event=pollend
- id=<pollid>
Message format:
@event=pollend;id=1234 :<target> !endpoll
3. Metadata and Message-Tags Usage
- All poll-related messages include message-tags such as 'event', 'id', 'question', 'options', etc.
- These tags ensure rich, machine-readable, and extensible message content.
- Optional tags like 'anonymous' can influence client UI and result privacy.
4. Implementation Guidelines
- Clients should parse message-tags to correctly identify poll events.
- Servers must support CAP obsidian/polls and associate message-tags accordingly.
- All poll actions should be logged server-side for audit and analytics purposes.
- Clients should verify the presence of the obsidian/polls cap before attempting to parse or send poll messages.
5. Security Considerations
- Vote validation must ensure that duplicate votes are prevented if not anonymous.
- Poll creator identity should remain confidential if anonymity is enabled.
- Unauthorized starting or ending of polls should be blocked.
- All message data should be sanitized to prevent injection or parsing errors.
6. Summary
The obsidian/polls capability, coupled with message-tags, offers a flexible, extendable, and secure polling framework within IRC channels. Clients and servers are encouraged to implement these standards to facilitate interactive and engaging conversations.
