Protocol Specification¶
Low-level protocol¶
PyCOM services talk to each other via 0MQ multipart messages via REP-REQ pair of sockets:
- Command (only CALL is supported now, response will contain either OK on success or FAIL on fatal protocol or server error)
- JSON content in UTF-8.
- (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)