Page: parsec http root connection
2020-09-03 14:09
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.