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.