Parsec.1 endpoint

WARNING: Work-In-Progress information provided for early access; all information on Parsec is subject to change!

This endpoint, situated behind parsec.HALO entry point, allows bidirectional and asynchronous command executions between client (party that had established the connection) and server (party that is serving incoming connections). The root parsec.1 endpoint has predefined and limited set of commands that allow to register, discover, document, and access higher-level applicaion services.

Introduction

As stated above, the parsec.1 functions after parsec.HALO layer which already provides secure channel with both ends authentication. The call/answer layer is implemented using FARCALL protocol in configuration capable of safely continue dropped session, which means silently ignoring "old" serials and not paying attention to possible gaps in the numbering.

General considerations and requirements

  1. The protocol is command-based, with async response, e.g. it is possible to execute several commands in parallel and get response in any order. Bot sides, server AND client, can issue commands. Neither of them should block and become irresponsible while waiting for the answer.

  2. The command based protocol uses FARCALL transport over parsec.halo transport.

  3. The commands at this level belong to some parsec layer, discussed below, and should not be directly updated and extended be the consumer, instead, consumer add specific content to the desired layer.

  4. Commands use named arguments. Returned value is always hash, possibly empty.

  5. Grave errors should be reported as FARCALL exceptions, and cause raising/throwing exception on the caller side, at the extend provided by the language. Lesser errors should be provided with return value. For example, we consider never use { status: 'OK'} - like answers - this is exactly where the farcall exception should be used. To select where to use exceptions it is useful to answer the question - whether the situation occur frequent and is rather variant of normal execution. If it is frequent or does not clearly requires interruption of the calling process, use returned value. Otherwise, use exception.

  6. Most often, commands come from the client. Unless specified else, the command being documented is called by the client.

Command layers

The main endpoint is the entry point that serves all sort of requests, including service commands layer, application API commands, content manipulation commands and so on. Commands in the layer share the same prefix, for example, session, service, etc. Command prefixes upt to the first dot characters actually are layers and can not be changed, used, extended by protocol users. Any changes to that are reserved to PARSEC developers and standards committee.

Let's discuss some simple layers that ma be found in early parsec implementations.

session support layer

Used to maintain session live and early detect connection problems.

session.ping(expected_period_seconds: Int=3) -> {}

client issues pings that server should answer (let farcall will do the rest) to check that the connection is alive. The expected_period_seconds is the time in seconds between client ping attempts. Before first ping, server assumes it as 3 seconds.

If the server does not receive ping in two consequent periods, it should consider connection lost, close the transport and marks session as awaiting reconnection. If the session is not reconnected for some period of time (it is upt to server to consider it) the session can and should be destroyed.

If the client does not receives answer to the ping command, it should consider connection being lost and should repeatedly try to re-establish it.

API layer

Web content layer

This is legacy layer used to transparently connect the http application server using parsec as the proxy.

web.access(method: String="get", path, params: {}, headers: {})
    -> { content_type: String="text/html", content: Any, headers: {} }

The legacy compatibility server software may consider map it it to html.get

New html content layer

This method replaces all the Zoo of http methods as it is equally good to get pages, post form data, post binary files and so on. In conjunction with data params (which are much more effective than application/json and form-multipart) and returned data (that is much more powerful replacement to response headers) it just do all the job.

html.get(path, params: {}, cache_tag: String=null) -> { html: String, data: {}, cache_tag: String }

Note about caching. If the resource provide cachetag, the client can send it back. If the server has the cachetag in a call, and somehow know that the result should be the same, it returns empty answer {} which means nothing has been changed and client should use cached value. It is up to the server how to define and use cache tag.

API layer

The main difference from the html content layer is discovery/documentation features that let API integration be more easy and effective. And, as always with parsec, API commands are binary-encoded, e.g. effective with multimedia parameters, encrypted with both end authenticated, duplex by nature (allowing pushes and symmetric async interfaces, also heavy loaded), all i is out of the box.

api.call(path: String, params: {}) -> { ... }

calls the api endpoint with any params and return whatever data as hash (as always in parsec)

api.discover(path="/") -> { api_endpoints: [
    { path: String, description: String },
    // ....
]}

list all endpoints available at some path with short description block. Full documentation is retrieved separately:

api.docs(path, format: String = 'markdown', cachetag: String=null) -> { markdown: String, cachetag: String=null }

Get full docs to some specific endpoint. The cache_tag meaning and usage is exactly same as for afore described html.get

Note about the format

As for now the preferred and required docs format is markdown as returning plain html causes many problems with sanitizing it and also requires a html styling standard be developed and followed.

Content and CORS

This requires investigation. As we do not use any insecure/untrusted mechanisms like cookies in the sessions, it may happen we need not special CORS restrictions. In the case parsec-capable browsers will need it, we wil reconsider its implementation.