0.preamble.md

The following documents describe:

• Content-Type to represent IRC messages and IRC Capability negotiation over HTTP
• HTTP API for sending IRC commands
  • My biggest use is sending messages "out of band" from push notifications, from a watch, from an out-of-process "share sheet" from another application to a bouncer.
• HTTP API for web hooks
  • This is a generic solution to solve "push notifications" from IRC (bouncer) in a flexible way.

1.irc-http-content-type.md

This document covers how IRC lines are represented over HTTP.

Content Negotiation

The content-negotiation feature of HTTP is used to declare the IRC capabilities.

For example, if the request was from a client aimed towards an IRC server. The following content-type and accept header should be used:

Content-Type: application/client+irc
Accept: application/server+irc

Capability Negotiation

A HTTP client can request server-time and echo-message capability.

Content-Type: application/client+irc
Accept: application/server+irc; server-time, echo-message

If the server allows both capabilities to be enabled, an example may look like the following:

> POST / HTTP/1.1
> Content-Type: application/client+irc
> Accept: application/server+irc; server-time, echo-message
> Connection: close
>
> PRIVMSG #palaver :Hello

< 200 OK
< Content-Type: application/server+irc; server-time, echo-message
<
< @time=... :kyle@palaver.chat PRIVMSG #palaver :Hello

If the server didn't accept echo-message, the following response may be found:

< 204 OK
< Content-Type: application/server+irc; server-time

2.irc-http.md

IRC HTTP API

The document below is a proposal for an IRC extension which exposes IRC via a HTTP API.

Advertisement

The presence of the Web API is advertised over IRC so that clients can discover them.

:irc.palaver.chat 005 kyle :CHANNELLEN=200 CHANTYPES=#& MODES=3 NICKLEN=9 HTTP=https://web.palaver.chat;bearer=dsfsdfsdf;session

Fields:

• bearer (string) - When present, represents a token linked to the current session
• session (boolean) - Indicates whether the bearer token only works during the life of the IRC connection. For bouncer type of IRC connections, the session MAY continue after disconnecting the IRC connection.

For example, using the bearer token to make a HTTP request to send a message:

> POST / HTTP/1.1
> Authorization: Bearer <username/password>
> Content-Type: irc, capbilities
> Accept: irc; capabilities
>
> PRIVMSG #test :Hello World!

< 204 OK

Assumptions

The HTTP protocol assumes that the server already supports labeled responses capability and the HTTP request creates an implicit labeled response which is the HTTP response from the request.

Example Use Cases

• Being able to send messages to the IRC server without connecting to IRC. Some examples of this could be out-of-process such as responding to a message from a watch etc where you do not want to create a full blown IRC connection and may not be able to.

• Send IRC Commands "out of band" from the IRC connection. For example, perhaps performing heavy commands outside of the IRC connection:

  • Chat History

  • LIST

  • WHO

  • HTTP connection can also be compressed using normal HTTP compression and caching mechanisms thus it may be possible to save significant bandwidth using compression for chat history requests.

3.irc-webhooks.md

IRC HTTP Web Hook

The document below is a proposal for an IRC extension which allows you to subscribe to events as a web hook.

Capability

CAP REQ palaver.chat/webhook

Web Hook API

• WEB-HOOK ADD
• WEB-HOOK REMOVE
• WEH-HOOK LIST

Examples

WEB-HOOK ADD https://foo.com/path echo-message,server-time PRIVMSG,NOTICE

How the request looks when any PRIVMSG or NOTICE command is received:

> POST /path HTTP/1.1
> Host: foo.com
> Content-Type: application/client+irc
> Accept: application/server+irc; server-time, echo-message
> Connection: close
>
> PRIVMSG #palaver :Hello

< 200 OK
< Content-Type: application/server+irc; server-time, echo-message
<
< @time=... :kyle@palaver.chat PRIVMSG #palaver :Hello

Unresolved questions:

• How can I provide functionality such as filtering or word matching (for PRIVMSG). I would like to do the following:
  • Receive any INVITE aimed at me
  • Receive PRIVMSG directly to me (not in channel)
  • Receive all PRIVMSG from channel #foo
  • Receive all PRIVMSG that conains my nick ({nick}) or another keyword
  • Recieve all PRIVMSG (except from doe)