Add section for hosting RPC server

This commit is contained in:
netkas 2024-09-02 19:53:33 -04:00
parent 6daf08d8bf
commit 7089a0609e

View file

@ -60,10 +60,15 @@ This project is licensed under GNU Free Documentation License v1.3, see the [LIC
* [Reserved Usernames](#reserved-usernames) * [Reserved Usernames](#reserved-usernames)
* [Regex Pattern (PCRE)](#regex-pattern-pcre) * [Regex Pattern (PCRE)](#regex-pattern-pcre)
* [RPC Communication](#rpc-communication) * [RPC Communication](#rpc-communication)
* [How to host the RPC server](#how-to-host-the-rpc-server)
* [Notification & Request-Response Communication](#notification--request-response-communication) * [Notification & Request-Response Communication](#notification--request-response-communication)
* [Request Object](#request-object) * [Request Object](#request-object)
* [Response Object](#response-object) * [Response Object](#response-object)
* [Error Response Object](#error-response-object) * [Error Response Object](#error-response-object)
* [Procedures](#procedures)
* [Establishing a connection](#establishing-a-connection)
* [Step 1: DNS Handshake](#step-1-dns-handshake)
* [Step 2: Establish Connection](#step-2-establish-connection)
* [Error Codes](#error-codes) * [Error Codes](#error-codes)
* [HTTP Status Codes](#http-status-codes) * [HTTP Status Codes](#http-status-codes)
* [-1xxx: RPC Errors](#-1xxx-rpc-errors) * [-1xxx: RPC Errors](#-1xxx-rpc-errors)
@ -109,6 +114,8 @@ Here, socialbox is the key, and the value is the URL of the Socialbox instance.
retrieve the TXT record, which then provides the URL of the Socialbox server.The client uses this URL to establish a retrieve the TXT record, which then provides the URL of the Socialbox server.The client uses this URL to establish a
connection to the Socialbox server. This process allows the client to dynamically discover the server URL. connection to the Socialbox server. This process allows the client to dynamically discover the server URL.
The domain name is usually resolved from a given peer address.
## Peer Address ## Peer Address
@ -183,6 +190,38 @@ standards. Below are the modifications made to the JSON-RPC 2.0 specification:
- Utilize HTTP status codes to indicate the status of the HTTP request-response cycle. For more details, refer to the - Utilize HTTP status codes to indicate the status of the HTTP request-response cycle. For more details, refer to the
"HTTP Status Codes" section under [Error Codes](#error-codes). "HTTP Status Codes" section under [Error Codes](#error-codes).
### How to host the RPC server
To host an RPC server, you must configure your domain name to have a subdomain that serves as the RPC endpoint for your
Socialbox instance. For example, if your domain is example.com, you can host the RPC server on the subdomain
socialbox.example.com. The RPC server should be accessible via HTTPS, and the root URL should be the RPC endpoint. For
example, the client would assume the RPC endpoint URL would look like this after preforming the [DNS Handshake](#dns-handshake):
```text
https://socialbox.example.com/
```
> You may use any subdomain name for the RPC endpoint, but the DNS TXT record should be placed in the main domain's DNS
and should contain the correct URL of the RPC endpoint.
Sub-Endpoints are not supported, the RPC endpoint URL **should not** contain any path or query parameter such as
```text
```text
- https://socialbox.example.com/rpc
- https://socialbox.example.com/rpc/endpoint
- https://socialbox.example.com/?rpc
- https://socialbox.example.com/?api
etc...
```
To break it down in three easy steps, say we want to talk to the server where `john@example.com` is hosted:
1. We resolve the domain name `example.com` to get the TXT record that contains the URL of the Socialbox instance.
2. `example.com` resolves to `socialbox.example.com` which is the RPC endpoint.
3. We assume the RPC endpoint URL is `https://socialbox.example.com/`
### Notification & Request-Response Communication ### Notification & Request-Response Communication
Notification requests are requests where the request object does not contain a request ID. The server processes these Notification requests are requests where the request object does not contain a request ID. The server processes these
@ -291,6 +330,39 @@ The fields in the error response object are as follows:
------------------------------------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------------
# Procedures
Procedures as described in the standard are methods that a server & client must implement to ensure compatibility with
other systems. These procedures are the core of the Socialbox standard and are required to be implemented by all
Socialbox servers and clients, these procedures can range from how an connection is established to how a user is
authenticated or how encryption is handled.
## Establishing a connection
When a client wants to connect to a Socialbox server, it must first perform a DNS handshake to discover the server URL.
For this example, let's assume the server is hosted on the subdomain socialbox.example.com. The client identified as
the peer `john@example.com` is trying to connect to the server to authenticate to it or even register an account if
john doesn't have one.
### Step 1: DNS Handshake
The client takes the peer's address and extracts the domain name, in this case, `example.com`. The client then resolves
the domain name to retrieve the TXT record that contains the URL of the Socialbox instance. The TXT record should be
placed in the main domain's DNS records with the following format:
```text
example.com. IN TXT "socialbox=socialbox.example.com"
```
For more details on the DNS handshake, refer to the [DNS Handshake](#dns-handshake) section under Specifications.
### Step 2: Establish Connection
Now the client figures out that the RPC endpoint for the Socialbox instance hosted under example.com is found at
`https://socialbox.example.com/`, the client then establishes a connection to the server using the URL. The client
------------------------------------------------------------------------------------------------------------------------
# Error Codes # Error Codes
Error codes are globally defined codes that represent the type of error that occurred during a method call. The error Error codes are globally defined codes that represent the type of error that occurred during a method call. The error