Service
ServerContext Class
- class RobotRaconteur.ServerContext
Context for services registered in a node for use by clients
Services are registered using the RobotRaconteurNode.RegisterService() family of functions. The ServerContext manages the services, and dispatches requests and packets to the appropriate service object members. Services may expose more than one object. The root object is specified when the service is registered. Other objects are specified through ObjRef members. A name for the service is also specified when the service is registered. This name forms the root of the service path namespace. Other objects in the service have a unique service path based on the ObjRef used to access the object.
Services may handle multiple connected clients concurrently. Each client is assigned a ServerEndpoint. The ServerEndpoint is unique to the client connection, and interacts with ServerContext to complete requests and dispatch packets. When the service needs to address a specific client, the ServerEndpoint or the ServerEndpoint.GetCurrentEndpoint() is used. (ServerEndpoint.GetCurrentEndpoint() returns the int local client ID.)
Service attributes are a varvalue{string} types dictionary that is made available to clients during service discovery. These attributes are used to help clients determine which service should be selected for use. Because the attributes are passed to the clients as part of the discovery process, they should be as concise as possible, and should not use user defined types. Use ServerContext.SetAttributes() to set the service attributes after registering the service.
Security for the service is specified using a ServiceSecurityPolicy instance. This policy is specified by passing as a parameter to RobotRaconteurNode.RegisterService(), or passing the policy to the constructor.
ServerContext implements authentication and object locking. Server side functions are exposed by ServerContext for authentication, object locking, and client management.
Clients using dynamic typing such as Python and MATLAB will only pull service types explicitly imported by the root object and objref objects that have been requested. Clients will not pull service types of user-defined named types if that service type is not explicitly imported. This can be problematic if new struct, pod, and/or namedarray types are introduced that do not have corresponding objects. Extra imports is used to specify extra service definitions the client should pull. Use ServerContext.AddExtraImport(), ServerContext.RemoveExtraImport(), and ServerContext.GetExtraImports() to manage the extra imports passed to the client.
- AddExtraImport(import_)
Add an extra service definition import
Clients using dynamic typing will not automatically pull service definitions unless imported by the root object or an objref. If new “struct”, “po”, or “namedarray” types are introduced in a new service definition type without a corresponding object, an error will occur. Use AddExtraImport() to add the name of the new service definition to add it to the list of service definitions the client will pull.
Service definition must have been registered using RobotRaconteurNode::RegisterServiceType()
- Parameters:
import (str) – The name of the service definition
- AddServerServiceListener(listener)
Add a service listener
- Parameters:
listener (Callable[[RobotRaconteur.ServerContext,int,object]]) – Callable listener function
- GetCandidateConnectionURLs()
Get the candidate connection URLs for this service. The candidate connection URLs are the URLs that can be used to connect to the service. The correct URL to use depends on the transport being used to connect to the service, and the network configuration of the client and service.
- Returns:
The candidate connection URLs
- Return type:
List[str]
- static GetCurrentServerContext()
Get the current ServerContext
Returns the current server context during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.
- Returns:
The current server context
- Return type:
- static GetCurrentServicePath()
Get the current object service path
Returns the service path of the current object during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.
- Returns:
The current object service path
- Return type:
str
- GetExtraImports()
Get the current list of extra service definition imports
- Returns:
The list of extra imports
- Return type:
List[str]
- GetNode()
Get the Node
- Return type:
- GetObjectLockUsername(servicepath)
Get the name of the user that has locked the specified service path
- Parameters:
servicepath (str) – The service path
- Returns:
The user owning the lock, or empty servicepath is not locked
- Return type:
str
- KickUser(username)
Kicks a user with the specified username
User must be authenticated.
- Parameters:
username (str) – The username to kick
- LogCandidateConnectionURLs(*args)
Log the candidate connection URLs for this service. See GetCandidateConnectionURLs() for more information.
- Parameters:
level (RobotRaconteur.LogLevel) – The log level to use. Defaults to RobotRaconteur.LogLevel_Info
- PrintCandidateConnectionURLs()
Print the candidate connection URLs for this service. See GetCandidateConnectionURLs() for more information.
- ReleaseObjectLock(servicepath, username, override_)
Release a client lock on servicepath
This function handles incoming client requests, but may also be used by the service directly. Client locks can be released by the user that created them if override_ is false, or by any user if override_ is true.
The override_ parameter is set to true for client requests if the client has the “objectlockoverride” permission.
- Parameters:
servicepath – The service path to release lock
username – The username requsting the lock release
override (bool) – If False, only the creating username can release the lock. If True, any username can release the lock
- ReleaseServicePath(path, endpoints=None)
Release the specified service path and all sub objects
Services take ownership of objects returned by objrefs, and will only request the object once. Subsequent requests will return the cached object. If the objref has changed, the service must call ReleaseServicePath() to tell the service to request the object again.
Release service path will release the object specified by the service path and all sub objects.
This overload will notify the specified that the objref has been released. If the service path contains a session key, this overload should be used so the session key is not leaked.
- Parameters:
path (str) – The service path to release
endpoints (List[int]) – (Optional) The client endpoint IDs to notify of the released service path, or None to notify all endpoints
- RemoveExtraImport(import_)
Removes an extra import service definition registered with AddExtraImport()
See AddExtraImport()
- Parameters:
import (str) – The name of the service definition
- Returns:
True The service definition was removed, False The service definition was not found in the extra imports vector
- Return type:
bool
- RequestClientObjectLock(servicepath, username, endpoint)
Request a client lock on servicepath for a specific client connection
This function handles incoming client requests, but may also be used by the service directly. Client object locks lock for a specific client connection, while client locks lock for a specific user. The specific client connection is specified using endpoint.
- Parameters:
servicepath (str) – The service path to lock
username (str) – The name of the user owning the lock
endpoint – The client endpoint ID of the client owning the lock
- RequestObjectLock(servicepath, username)
Request an object lock on servicepath for user username
This function handles incoming client requests, but may also be used by the service directly
- Parameters:
servicepath (str) – The service path to lock
username (str) – The name of the user owning the lock
- SetServiceAttributes(attributes)
Set the service attributes
Sets the service attributes. Attributes are made available to clients during service discovery. Attributes should be concise and not use any user defined types.
- Parameters:
attr (Dict[str,Any]) – The service attributes
ServerEndpoint Class
- class RobotRaconteur.ServerEndpoint
Server endpoint representing a client connection
Robot Raconteur creates endpoint pairs between a client and service. For clients, this endpoint is a ClientContext. For services, the endpoint becomes a ServerEndpoint. ServerEndpoints are used to address a specific client connected to a service, since services may have multiple clients connected concurrently. ServerEndpoints also provide client authentication information.
Use ServerEndpoint.GetCurrentEndpoint() to retrieve the int32 current endpoint ID. Use ServerEndpoint.GetCurrentAuthenticatedUser() to retrieve the current user authentication information.
- static GetCurrentAuthenticatedUser()
Returns the current authenticated user
Users that have been authenticated have a corresponding AuthenticatedUser object associated with the ServerEndpoint. GetCurrentAuthenticatedUser() returns the AuthenticatedUser associated with the current ServerEndpoint during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.
Throws PermissionDeniedException or AuthenticationException if there is no AuthenticatedUser set in the current thread.
- Returns:
The AuthenticatedUser
- Return type:
- static GetCurrentEndpoint()
Returns the current server endpoint
Returns the current server endpoint during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.
Throws InvalidOperationException if not during a request or packet event
- Returns:
The current server endpoint id
- Return type:
int