~emersion/soju-dev

Specify soju's namespace extension v1 PROPOSED

Hubert Hirtz: 1
 Specify soju's namespace extension

 1 files changed, 152 insertions(+), 0 deletions(-)
Export patchset (mbox)
How do I use this?

Copy & paste the following snippet into your terminal to import this patchset into git:

curl -s https://lists.sr.ht/~emersion/soju-dev/patches/15392/mbox | git am -3
Learn more about email & git
View this thread in the archives

[PATCH] Specify soju's namespace extension Export this patch

---
 doc/namespace.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 doc/namespace.md

diff --git a/doc/namespace.md b/doc/namespace.md
new file mode 100644
index 0000000..04ff701
--- /dev/null
+++ b/doc/namespace.md
@@ -0,0 +1,152 @@
---
title: soju's namespace extension
layout: spec
work-in-progress: true
license: CC BY 4.0 <https://creativecommons.org/licenses/by/4.0/>
copyrights:
  -
    name: "Hubert Hirtz"
    email: "hubert@hirtz.pm"
    period: "2020"
---


## Notes for implementing vendor-specific version

This is a vendor-specific specification.

Software implementing this vendor-specific specification MUST NOT use the
unprefixed `namespace` capability/tag name. Instead, implementations SHOULD
use the `soju.im/namespace` capability/tag name to be interoperable with other
software implementing a compatible vendor-specific version.

The final version of the specification will use an unprefixed capability name.


## Introduction

This extension allows multiplexing several IRC connections on top of a single
TCP stream, and is mainly written with bouncers in mind.

Connection multiplexing offers the following advantages:

- for clients, and especially embedded devices, it reduces battery consumption
  ([source]),
- for servers, it reduces the number of connections to manage, and thus reduces
  memory usage.

[source]: ??


## Architecture

This extension introduces the `namespace` capability, the `namespace` message
tag, and the `NAMESPACE` command.

The `namespace` capability has no associated value.

The `NAMESPACE` command has one and exactly one parameter, like so:

    NAMESPACE +reference-tag
    NAMESPACE -reference-tag

The reference tag follows the same syntax as a batch reference tag.

The `namespace` tag has a mandatory, opaque, associated value.

Full support for this extension requires support for the `cap-notify`
capability. However, servers MAY allow connection multiplexing for clients that
do not support `cap-notify`.

### Connection life cycle

This section assumes `namespace` has been successfully negotiated.

The underlying IRC connection, which has been used to negotiate the capabilities
required by this extension, is called the **parent connection**.  The IRC
connections initiated from the use of this extension are called **child
connections**.

Child connections are initiated by the server.

A child connection is opened by the `NAMESPACE` command whose parameter begins
with a PLUS (`+`) sign.  A child connection is closed by the `NAMESPACE` command
whose parameter begins with a MINUS (`-`) sign.  What comes after these signs is
the identifier of the child connection.

Messages that feature a `namespace` tag belong to the child connection whose
identifier is the tag value.  Messages that do not feature such a tag, or
message whose `namespace` tag does not hold a valid, known identifier belong to
the parent connection.

Child connections start with the same state any IRC connection would have after
the following, assumed successful, steps happened:

- NICK,
- USER,
- an optional capability negotiation.

In other words, servers MUST send an RPL_WELCOME burst on this child connection
first.

Child connections inherit the following information, and only the following
information from the parent connection:

- Enabled capabilities,
- Client user name and real name,

In particular, child connections do *not* inherit the following information from
the parent connection:

- the client nickname, which is reported as the first parameter of the
  child connection's RPL_WELCOME,
- the server name, which is reported as the prefix of the child connection's
  RPL_WELCOME,
- ISUPPORT tokens and values,
- user and channel information,
- ongoing batches.


### Examples

#### A single child connection

In this example, a client registers itself to a server. The client requests the
necessary capabilities to enable this extension and receives the welcome burst
from the parent connection, followed by the opening of a child connection called
`nsnet`, followed by the welcome burst of this child connection.

```
Client: CAP REQ :cap-notify soju.im/namespace
Client: NICK nick
Client: USER u s e r
Server: :example.com CAP ACK :cap-notify soju.im/namespace
Client: CAP END
Server: :example.com 001 nick :Welcome home, nick
Server: :example.com ...
Server: :example.com 376 nick :The end of the MOTD/welcome burst
Server: NAMESPACE +nsnet
Server: @namespace=nsnet :ns.net 001 dan- :Welcome to the Internet Relay Network, dan-
Server: @namespace=nsnet :ns.net ...
Server: @namespace=nsnet :ns.net 376 nick :The end of the MOTD/welcome burst
```

#### Use of `cap-notify`

In this example, the client requests capabilities unrelated to this extension,
which are accepted by the server.  Then the server opens the same child
connection to `nsnet`, and sends a `CAP DEL` to remove the supplementary
capabilities from the child connection.  The client can still use those on the
parent connection, and it does use one with the last message.

```
Client: CAP REQ :cap-notify soju.im/namespace message-tags multi-prefix extended-join
Server: :example.com CAP ACK :cap-notify soju.im/namespace message-tags multi-prefix
Server: NAMESPACE +nsnet
Server: @namespace=nsnet :example.com CAP DEL :multi-prefix message-tags
Server: @namespace=nsnet :ns.net 001 dan- :Welcome to the Internet Relay Network, dan-
Server: @namespace=nsnet :ns.net ...
Client: @namespace=nsnet JOIN #ircdocs
Server: @namespace=nsnet :dan-!~dan@ircdocs.horse JOIN #ircdocs dan- :The 7th Dan
Client: @+typing=active TAGMSG e
```
-- 
2.26.2