PyCOM 0.6.0 documentation

Protocol Specification

Low-level protocol

PyCOM services talk to each other via 0MQ multipart messages via REP-REQ pair of sockets:

  1. Command (only CALL is supported now, response will contain either OK on success or FAIL on fatal protocol or server error)
  2. JSON content in UTF-8.
  3. (optional, not implemented yet) binary attachment

Top-level request object contains the following properties:

version

(string) protocol version, should be 1.0 now

interface

(string) requested interface name (see below)

method

(string) requested method name

session_id

(string or null, optional) current session identifier

args

(anything) any JSON entity to be passed as an argument to method

extensions

(JSON object, optional) object with extensions data

Top-level response object contains the following properties:

code

(number) result code (0 for success)

error

(string, optional) error message

session_id

(string or null) current session identifier

result

(anything) any JSON entity that was returned from method

extensions

(JSON object, optional) object with extensions data

Standard services remote API

NameServer

`org.pycom.nameserver`

Remote interface for registering and locating interfaces and services.

stat()

Ping method. Can be used to check whether nameserver is alive. Will return some statistics in the future.

register()

Registers interface. Argument is a dictionary with the following keys:

interfaces

(list of strings) interfaces to register

address

(string) 0MQ address of service

service

(string) service name

locate()

Locates service by interface and service name. Argument is a dictionary with the following keys:

interface

(string) interface to locate

service

(string, optional) service name to locate

Result is a dictionary with the following keys:

address

(string) 0MQ address of service

service

(string) service name

interfaces

(list of strings) list of provided interfaces

list_services()

List all known services. Argument is a dictionary with the following keys:

interface

(string, optional) if present, return only services with interface that matches given regular expression from the beginning. See examples for service. Not that dots must be escaped in regular expressions!

service

(string, optional) if present, return only services with name that matches given regular expression from the beginning. E.g. /org/pycom/nameserver matches:

/org/pycom
.*/pycom
/(org|com)/pycom
/org/pycom/nameserver$

but does NOT match:

/pycom
/org/pycom/nameserver/1

Result is a list of dictionaries with the following keys:

address

(string) 0MQ address of service

service

(string) service name

interfaces

(list of strings) list of provided interfaces

Authenticator

`org.pycom.authenticator`

Remote interface for authenticating users. There is no such service in PyCOM distribution. Why? Well, because the exact authentication procedure may differ broadly. You have to write an appropriate service yourself.

authenticate()

Validate user’s credentials and generate a random token for the current session.

user

(string) user name

credentials

(anything) any credentials the user can provide

Result is a dictionary with the following keys:

token

(string) generated token for identifying user’s session

validate()

Validate a token and return user’s info.

token

(string) unique token

Result is a dictionary with the following keys:

name

(string) user name

roles

(list of strings) user roles (exact interpretation depends on implementation)