Add section for hosting RPC server
This commit is contained in:
parent
6daf08d8bf
commit
7089a0609e
1 changed files with 72 additions and 0 deletions
72
README.md
72
README.md
|
@ -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
|
||||||
|
|
Loading…
Add table
Reference in a new issue