ObsidianIRC polls spec: Difference between revisions

From H4KS
Jump to navigationJump to search
Created page with "=ObsidianIRC IRCv3 Extension Specification for Polls= ==Introduction== This document describes the ObsidianIRC vendored spec for implementing polls within IRC channels. This specification includes extension capabilities, message formats, and relevant metadata to enable structured and interactive polling experiences. ==Overview== The polls extension is designed to allow clients and servers to facilitate poll creation, voting, and result display within IRC channels using..."
 
No edit summary
 
Line 1: Line 1:
=ObsidianIRC IRCv3 Extension Specification for Polls=
== ObsidianIRC Polls Specification ==


==Introduction==
=== Overview ===
This document describes the ObsidianIRC vendored spec for implementing polls within IRC channels. This specification includes extension capabilities, message formats, and relevant metadata to enable structured and interactive polling experiences.
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.


==Overview==
=== 1. Extension Capabilities ===
The polls extension is designed to allow clients and servers to facilitate poll creation, voting, and result display within IRC channels using standardized message formats and metadata. It extends the IRCv3 protocol, ensuring compatibility and extensibility.


==Extension Capabilities==
==== 1.1 obsidian/polls Cap ====
;Capability Name: <code>obsc-polls</code>
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.
:Allows clients and servers to negotiate and activate polling features.


==Message Formats==
==== 1.2 Negotiation ====
;Poll Creation (<code>PRIVMSG</code>):
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.
''Format:''
<pre>
:client!user@host PRIVMSG #channel :/poll create "Question text" option1 option2 [option3 ...]
</pre>
''Description:'' Initiates a new poll with the specified question and options.


;Vote Submission (<code>PRIVMSG</code>):
=== 2. Message Formats ===
''Format:''
<pre>
:client!user@host PRIVMSG #channel :/vote [poll''id] [option''number]
</pre>
''Description:'' Casts a vote for a specified option in a poll identified by poll''id.


;Poll Results (<code>NOTICE</code> or <code>PRIVMSG</code>):
==== 2.1 Initiating a Poll ====
''Format:''
Clients initiate a poll using a PRIVMSG with specific message-tags and metadata. Example:
<pre>
:server HOST NOTICE #channel :Poll [poll''id] results: Option1: votes, Option2: votes...
</pre>
''Description:'' Reports the current results of an active poll.


==Metadata Description==
TAGs:
;Poll ID:
* event=poll''start
Unique identifier for each poll, assigned at creation.
* id=<poll''id>
* question=<UTF-8 string>
* options=<list of options>
* anonymous=<true/false (optional)>


;Question:
Message format:
The poll question text.


;Options:
@event=poll''start;id=1234;question=What is your favorite color?;options=Red,Blue,Green;anonymous=false :<target> !poll
List of answer options, each assigned a number.


;Votes:
==== 2.2 Voting ====
Number of votes per option.
Users submit votes similarly, with message-tags indicating vote event:


==Extensions and Metadata Capabilities==
TAGs:
This spec supports the following extensions:
* event=poll''vote
* Real-time voting updates.
* id=<poll''id>
* Persistent polls that retain state across sessions.
* option=<option''value>
* Poll expiration and time-based closure.


==Implementation Notes==
Message format:
* Clients should display poll questions and options clearly.
* Voting commands should be validated to prevent multiple votes from the same user if restrictions apply.
* Results should be updated dynamically as votes are cast.


==Security and Privacy Considerations==
@event=poll''vote;id=1234;option=Blue :<target> !vote
The protocol should ensure user anonymity if required, and prevent vote manipulation through proper validation.


==Conclusion==
==== 2.3 Ending or Closing a Poll ====
This IRCv3 spec for polls provides a comprehensive framework to build interactive and standardized polling mechanisms within IRC channels using ObsidianIRC extensions.
Polls can be ended either by the poll creator or by server policy:


For further updates or contributions, refer to the project repository and community discussions.
TAGs:
* event=poll''end
* id=<poll''id>
 
Message format:
 
@event=poll''end;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.

Latest revision as of 19:15, 31 August 2025

ObsidianIRC Polls Specification[edit]

Overview[edit]

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[edit]

1.1 obsidian/polls Cap[edit]

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[edit]

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[edit]

2.1 Initiating a Poll[edit]

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[edit]

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[edit]

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[edit]

  • 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[edit]

  • 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[edit]

  • 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[edit]

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.

Retrieved from "https://wiki.h4ks.com/index.php?title=ObsidianIRC_polls_spec&oldid=783"