From e9d360a5283b5c626d91c6f52aefd80938c58b4d Mon Sep 17 00:00:00 2001 From: DavidCo113 Date: Wed, 31 May 2023 02:59:00 +0000 Subject: [PATCH 1/2] Miscellaneous changes for extensions.md --- extensions.md | 62 ++++++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 28 deletions(-) diff --git a/extensions.md b/extensions.md index 446c7fa..a0472e1 100644 --- a/extensions.md +++ b/extensions.md @@ -2,56 +2,62 @@ ### Overview -Each extension is given an unique id that is decided when it is first -registered. We differentiate between two types of packets: - -*Those that:* +Each extension is given a unique ID that is decided when it is first +registered. We differentiate between two types of extensions: | Type | Purpose | Extension id range | | ------------- | ------------------------------------- | ------------------ | -| `HAS_PACKETS` | introduce new packets to the protocol | 0-191 | -| `PACKETLESS` | don't use and need any packets | 192-255 | - -Each extension is given one legacy packet id equal to `64+extension_id`. -For `PACKETLESS` extensions this would mean that their packet ids are out -of spec `>255`, thus they don't have any. -An example for a packetless extension would be *OpenSpades'* UnicodeExt. - -Each extension packet will contain 1 additional byte in its data, which is a -subpacket id, used to have multiple packets available for each extension. This -is always the case, even if an extension only needs 1 packet in total. +| `HAS_PACKETS` | Introduce new packets to the protocol | 0-191 | +| `PACKETLESS` | Don't have any packets | 192-255 | + +Each extension is given one legacy packet ID equal to `64+extension_id`. +For a `PACKETLESS` extension this would mean that its packet ID is out +of range for the UByte used to store IDs (UByte values range from 0 to 255). +Therefore, it cannot support packets. An example of a `PACKETLESS` extension +would be the [Message Types](https://github.com/piqueserver/aosprotocol/issues/14) +extension, with an extension ID of 193. Note that OpenSpades' UTF-8 extension +used to be used here as the example, but this extension actually does NOT use +`ExtInfo`! Instead, UTF-8 encoded messages are prefixed with a 0xFF byte. + +Each extension packet contains 1 byte in its data after the packet ID, which is a +subpacket ID that used to have multiple packets available for each extension. This +is always the case, even if an extension only needs 1 packet in total. The reason +for this is unknown, considering the version of all extensions supported by either +the client OR the server are specified in the `ExtInfo` transaction, which should +make it easily possible to tell if the extension is a version that needs more than +one packet or not. General extension packet structure: -| Field name | Type | Notes | -| ------------- | --------- | -------------- | -| Packet id | UByte | 64-255 | -| Sub packet id | UByte | 0-255 | -| Data | UByte[] | extension data | +| Field name | Type | Notes | +| ------------ | --------- | -------------- | +| Packet ID | UByte | 64-255 | +| Subpacket ID | UByte | 0-255 | +| Data | UByte[] | Extension data | ### ExtInfo Packet * Packet ID: 60 -* Total size: `2+2*length` +* Total size: `2+2*Length` | Field name | Field type | Notes | | ---------- | ------------ | ---------------------------- | -| length | UByte | `length` entries will follow | -| entries | ExtInfoEntry | see below | +| Length | UByte | `Length` entries will follow | +| Entries | ExtInfoEntry | See below | **ExtInfoEntry** | Field name | Field type | Notes | | ---------- | ---------- | ------------------- | -| ext. ID | UByte | see #Overview | -| version | UByte | Usually starts at 1 | +| Ext. ID | UByte | See #Overview | +| Version | UByte | Usually starts at 1 | ## Protocol Flow -The server should send an `ExtInfo` packet (optimally) after the Version Info response has been received to compatible clients +The server should send an `ExtInfo` packet (optimally) after the Version Info response has been received and checked to be from a compatible client (OpenSpades versions > 0.1.3, see https://github.com/piqueserver/piqueserver/issues/504), -assuming it supports any. The client can store the list of extensions for later use and should -reply with an `ExtInfo` packet that lists the extensions it supports (if it does actually support any). +assuming the server supports any. The client can store the list of extensions for later use and should +reply with an `ExtInfo` packet that lists the extensions *it* supports (if it does actually support any). The client can omit any extensions that the server does not support from its reply, but this is not necessary as the server can simply ignore them itself. From 96a30cba07be066e892c1b7c92be0fe0c37fee17 Mon Sep 17 00:00:00 2001 From: DavidCo113 Date: Wed, 31 May 2023 03:27:45 +0000 Subject: [PATCH 2/2] remove "used to be used here" --- extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions.md b/extensions.md index a0472e1..14ce6bc 100644 --- a/extensions.md +++ b/extensions.md @@ -16,7 +16,7 @@ of range for the UByte used to store IDs (UByte values range from 0 to 255). Therefore, it cannot support packets. An example of a `PACKETLESS` extension would be the [Message Types](https://github.com/piqueserver/aosprotocol/issues/14) extension, with an extension ID of 193. Note that OpenSpades' UTF-8 extension -used to be used here as the example, but this extension actually does NOT use +used to be here as the example, but this extension actually does not use `ExtInfo`! Instead, UTF-8 encoded messages are prefixed with a 0xFF byte. Each extension packet contains 1 byte in its data after the packet ID, which is a