Skip to content
This repository was archived by the owner on Aug 15, 2025. It is now read-only.

Commit f9b4998

Browse files
committed
add sections for http and ip
1 parent 64901c1 commit f9b4998

File tree

1 file changed

+28
-4
lines changed
  • docs/Protocol Specifications

1 file changed

+28
-4
lines changed

docs/Protocol Specifications/core.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,12 @@ of the specification document: **v0.1.0-alpha.1**
2020
- [polyproto Specification](#polyproto-specification)
2121
- [1. Terminology used in this document](#1-terminology-used-in-this-document)
2222
- [2. Trust model](#2-trust-model)
23-
- [3. APIs and communication protocols](#3-apis-and-communication-protocols)
23+
- [3. APIs and underlying communication protocols](#3-apis-and-underlying-communication-protocols)
2424
- [3.1 `.well-known`](#31-well-known)
2525
- [3.2 WebSockets](#32-websockets)
2626
- [3.2.1 Events over REST](#321-events-over-rest)
27+
- [3.3 HTTP](#33-http)
28+
- [3.4 Internet Protocol (IP)](#34-internet-protocol-ip)
2729
- [4. Federated identity](#4-federated-identity)
2830
- [4.1 Authentication](#41-authentication)
2931
- [4.1.1 Authenticating on a foreign server](#411-authenticating-on-a-foreign-server)
@@ -114,7 +116,7 @@ polyproto operates under the following trust assumptions:
114116
6. Users rely on their home server for identity key certification, without the home server
115117
possessing the identity.
116118

117-
## 3. APIs and communication protocols
119+
## 3. APIs and underlying communication protocols
118120

119121
The polyproto specification defines a set of [APIs](https://apidocs.polyproto.org).
120122
In addition to these REST APIs, polyproto employs WebSockets for real-time communication between
@@ -251,6 +253,28 @@ Polling a REST endpoint is inherently inefficient and therefore should only be d
251253
ranging from a few minutes to a few days. If a client requires information more often than that,
252254
then a WebSocket connection should be considered.
253255

256+
### 3.3 HTTP
257+
258+
HTTP/1.1 is the minimum required version that polyproto servers and clients must implement.
259+
Implementing HTTP/2 and HTTP/3 is strongly recommended for all use cases, as both versions of the
260+
protocol introduce significant performance improvements over HTTP/1.1 with HTTP/3 reducing latency
261+
and improving performance the most, especially over lossy networks.
262+
263+
Future versions of the polyproto specification may mandate the implementation of HTTP/2.
264+
265+
### 3.4 Internet Protocol (IP)
266+
267+
Support for both versions 4 and 6 of the Internet Protocol (IPv4 and IPv6) is mandatory for
268+
polyproto client and server software. Real-world availability of both versions of the Internet
269+
Protocol in polyproto should happen on a best-effort basis.
270+
271+
!!! example "Explanation"
272+
273+
We do not mandate that access to a polyproto server must be possible over both IPv4 and IPv6
274+
as most of the world is not sufficiently IPv6 capable. We do, however, mandate that software
275+
written to support polyproto must be capable of handling traffic over both IPv4 and IPv6, should
276+
both versions of the Internet Protocol be available to the software at runtime.
277+
254278
## 4. Federated identity
255279

256280
The federation of actor identities allows users to engage with foreign servers as if they were their
@@ -503,8 +527,8 @@ Actors must use a separate ID-Cert for each client or session they use. Separati
503527
limits the potential damage a compromised ID-Cert can cause.
504528

505529
For two implementations of polyproto to be interoperable, they must support an overlapping set of
506-
digital signature algorithms. See [Section 6.5](#65-cryptographic-recommendations) for more
507-
information on cryptographic recommendations.
530+
digital signature algorithms. See [Section 6.5](#65-cryptographic-specifications) for more
531+
information on cryptographic specifications.
508532

509533
#### 6.1.1 Structure of an ID-Cert
510534

0 commit comments

Comments
 (0)