versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2025-12-06 06:18:19 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity
docs/docs/spec.md
Jesse Wierzbinski 33cd650ad5
Fix dead links
2024-03-17 20:29:00 -10:00

5.3 KiB
Raw Blame History

Introduction

The Lysand Protocol is designed as a communication medium for federated applications, leveraging the HTTP stack. Its simplicity ensures ease of implementation and comprehension.

Distinct from ActivityPub, Lysand incorporates an extensive range of built-in features tailored for social media applications. It prioritizes security and privacy by default.

Lysand aims for standardization, discouraging vendor-specific implementations, as seen in Mastodon's adaptation of ActivityPub. It relies on straightforward JSON objects and HTTP requests, eliminating the need for complex serialization formats.

This repository provides TypeScript types for every object in the protocol, facilitating easy adaptation to other languages.

Design Goals

While Lysand draws parallels with popular protocols like ActivityPub and ActivityStreams, it is not compatible with either. It also does not support ActivityPub's JSON-LD serialization format.

Lysand-compatible servers may choose to implement other protocols, such as ActivityPub, but it is not a requirement.

Implementation Requirements

All HTTP request and response bodies MUST be encoded as UTF-8 JSON, with the Content-Type header set to application/json; charset=utf-8. If the server supports cryptography, a Signature header as defined in [/signatures](the signatures spec) MUST also be present.

Servers MUST use UUIDs or a UUID-compatible system for the id field. Any valid UUID is acceptable, but it should be unique across the entire known network if possible. However, uniqueness across the server is the only requirement.

Note

Protocol implementers may prefer UUIDv7 over the popular UUIDv4 for their internal databases, as UUIDv7 is lexicographically sortable by time generated. A PostgreSQL extension is available here.

All URIs MUST be absolute and HTTPS, except for development purposes. They MUST be unique across the entire network and MUST contain the id of the object in the URI. They should not contain mutable data, such as the actor's username.

All URIs MUST be normalized and MUST NOT contain any query parameters. URI normalization is defined in RFC 3986 Section 6. Servers MUST reject any requests with non-normalized URIs.

Definitions

The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document as defined in RFC 2119.

  • Actor: An individual or entity utilizing the Lysand protocol, analogous to ActivityPub's Actor objects. An actor could be a Server Actor, representing a server, or a User Actor.
  • Server: A server that deploys the Lysand protocol, referred to as an implementation. Servers are also known as instances.

Universal Guidelines

While some servers may choose to relax these rules for incoming content, provided it doesn't induce errors or edge cases, these guidelines are crucial for outgoing content.

JSON Object Handling

All JSON objects disseminated during federation MUST be handled as follows:

  • The object's keys MUST be arranged in lexicographical order.
  • The object MUST be serialized using the Canonical JSON format.
  • The object MUST be encoded using UTF-8.
  • The object MUST be signed using either the Server Actor or the Actor object's private key, depending on the context. (Signatures and keys are governed by the rules outlined in the Keys and Signing spec). Signatures are encoded using request/response headers, not within the JSON object itself.

Requests and Responses

All HTTP requests MUST be transmitted over HTTPS. Servers MUST NOT accept HTTP requests, unless for development purposes (e.g., if a server is operating on localhost or another local network).

Servers should support HTTP/2 and HTTP/3 for enhanced performance and security. Servers MUST support HTTP/1.1 at a minimum.

Requests

All requests MUST include at least the following headers:

  • Accept: application/json
  • Content-Type: application/json; charset=utf-8 if the request contains a body
  • Signature if the request body is signed (which is typically the case)

Additionally, requests SHOULD include the following headers (though not mandated by the protocol):

  • User-Agent with a value that identifies the client software

Responses

All responses MUST include at least the following headers:

  • Content-Type: application/json; charset=utf-8 if the response contains a body
  • Signature if the response body is signed (which is typically the case)
  • Cache-Control: no-store on entities that can be edited directly without using a Patch, such as Actors
  • A cache header with a max-age of at least 5 minutes for entities that are not expected to change frequently, such as Notes
  • A cache header with a large max-age for media files when served by a CDN or other caching service under the server's control