RealityServer Web Services API Programmer's Manual

Overview of the RealityServer Web Services API

RealityServer Web Services provides an interface between the HTTP and RTMP protocols and neuray Services. It's major function is to convert HTTP/RTMP requests into service commands and commands responses into HTTP/RTMP responses.

On its own RealityServer Web Services simply provides a framework for this conversion. The actual work of converting from request -> command -> response is handled by extension plugins. Whilst support for various industry standard RPC protocols is provided (currently JSON-RPC versions 1.0 and 2.0) the user is able to implement additional protocols if required.

Implementation

RealityServer Web Services exposes all extension interfaces provided by the neuray Services API. In addition it is possible to provide custom implementations for the following functionality: Implementation of each of these follows a common pattern. Each provides a get_name() method whose result is used to identify the implementation in the system. There may also be various methods to information to the system on how to execute the implementation. Finally there are one or more handlers which are called to execute the desired functionality. These can be identified as the methods taking a 'context' argument. In the case of Authorization and State handlers there will be one method for HTTP requests and one for RTMP requests. The user need only implement the handlers for protocols they are using, if RTMP or HTTP is not being used the handlers can simply return false.

Plugins

Extensions are installed using a custom plugin type, mi::rswservices::IServices_plugin. These plugins are installed into the Neuray Library like any other Neuray Library plugin. On Web Services startup the plugins initialize method is called and it may use the provided context to install any user implemented code. It is also possible to retain the context to add and remove code at a later time.

Plugin initializing occurs in the same order as plugins were loaded. Plugins are loaded in the order their directories are specified in the configuration file. Files with these directories are loaded in alphabetical order. This defines the order in which commands are installed. Any commands installed whose name and namespace match the name of already installed commands will overwrite the earlier one.

Note that all implementations installed via mi::rswservices::IServices_plugin must be thread safe as they may be called simultaneously from multiple threads.

HTTP Request Processing

An incoming HTTP request is processed as follows:
  1. User Access Control. If UAC is enabled then user access is processed first. If access is denied then a 503 HTTP error is returned.
  2. Authorization. If an Authorizer is configured for the incoming URL then it is called to authorize the connection.
  3. State Handling. All configured State handlers for the incoming URL are called. State handlers have the opportunity to modify the incoming request and setup the neuray Services execution environment.
  4. Static content serving. If the HTTP request is for a file in the content root then the file is served and processing ceases.
  5. Live documentation serving. If the HTTP request is for live documentation then the documentation is served.
  6. Protocol processing. Finally the HTTP request is passed through all registered protocol processors. If one of these identifies the request then commands are decoded from the request, executed, and their responses protocol encoded and delivered back to the HTTP client.
Steps 2, 3, and 6 can all be controlled via the RealityServer Web Services API by installing an appropriate handler. Event handlers can also be installed that are called when sessions are created or destroyed at step 1.

RTMP Request Processing

RTMP requests are fundamentally different to HTTP requests. An HTTP session will consist of many individual HTTP requests each of which must be treated as completely separate and each go through the entire processing sequence. RTMP sessions however are long lived and a single connection is typically used for the entire session and will contains multiple RPC requests. Additionally, one or more video streams are typically sent over the connection and controlled on the server side as opposed to individual image requests polled from the client. Finally, protocol processing is not support by the RTMP server. RealityServer Web Services uses the native RPC and AMF encoding provided by RTMP as the command protocol.

Am RTMP connection is processed as follows:
  1. Initial connection. If an Authorizer is configured for the "tcURL" connection argument (the URL provided to NetConnection.connect()) then it is called to authorize the connection.
  2. RPC calls.
    1. State Handling. Configured State handlers are identified from either the connection URL or URL provided to the RCP. Any found handlers are called and can perform the same functions as in an HTTP request.
    2. The command request is decoded, executed and it's results returned to the client, if requested.
  3. Stream creation. Multiple streams can be created within the RTMP connection. Each stream can play a Stream Encoder which associates a video codec with a render handler. Users may implement their own render handlers to provide custom rendering within an RTMP stream.
Static content and live documentation cannot be served over an RTMP connection.

Path Mapping

RealityServer Web Services overrides the default path mapper provided by neuray Services. The overridden mapper, instead of mapping relative paths to the content root takes them relative to the URL path within the content root. For example a request to load the file 'scenes/main.mi' made to the URL 'http://host:port/applications/car_configurator/' will attempt to load the file '$CONTENT_ROOT/applications/car_configurator/scenes/main.mi' as opposed to '$CONTENT_ROOT/scenes/main.mi'.

This same rule applies in RTMP except it uses the URL used during the RTMP connection or the State URL provided to an RPC request.

Configuration

The RealityServer configuration is made available to all plugins. This can be used to query any standard configuration item. Additionally the configuration format supports <user> directives which may be used to specify arbitrary configuration information. Plugins may query <user> directives to find their own configuration items instead of defining and discovering their own configuration files.

Note that the configuration supplied is read only, plugins are not able to reconfigure RealityServer dynamically.