Parsec HTTP root connection

The parsec protocol rely on some sort of remote procedure call layer to implement its base, parsec session. This is whar root connection is all about.

This artice presents recommended specification for http/https based root level connection.

Note that as Parsec does not use and depends on TLS/SSL, the http is a preferable way to communicate as https not just add more latency and battery drain, but introduce culnerability to a wide range of attacks, see why parsec?.

Request

To implement parsec command, the HTTP POST client issues request to the standard path on the service host:

HTTP POST /api/p1

api/p1 is a standard oath for parsec 1.x endpoint.

The requets is in miltipart/form-data format with the single element cmd of type 'file attachment' with binary encoded (BOSS) parsec command with arguments (see below).

The resutl is again encoded with boss and returned as binary application/octet-stream.

Command format

Boss-encoded dictionary as:

{
    "cmd": string,
    "args": {
        // any parameters
    }
}

Command result

Boss-encoded dictionary as (using typescript notation):

{
    result?: { 
        // any result data, maybe empty, if no error is reported
    },
    // if an error has been occured, result is missing and the error definition
    // should be present instead:
    error?: {
        // error code is a stable, iummutable error type constant, the 
        // software should rely on it in error processing:
        code: string, 
        // text could be any human0readable, uusing http header extraced
        // locale and intended to be shown to end user
        text?: string 
    }
}    

Importnt. Result should always contain either result or error. Error reporing should normally be used in place of exception raising and should be treated as exception throwing cause in client library. For example kotlin and typescript libraries raises special kind of exception.

The HTTP status should be 200 if result is present and 400+ otherwise, with at least error.code in body.