The gemstone module (main classes)

Core classes

class gemstone.MicroService(io_loop=None)

The base class for implementing microservices.

Parameters:io_loop – A tornado.ioloop.IOLoop instance - can be used to share the same io loop between multiple microservices running from the same process.

Attributes

You can (and should) define various class attributes in order to provide the desired functionality for your microservice. These attributes can be configured at runtime by using the configurable sub-framework (read more at Configurable features )

Identification

MicroService.name = None

The name of the service. Is required.

MicroService.host = '127.0.0.1'

The host where the service will listen

MicroService.port = 8000

The port where the service will bind

MicroService.endpoint = '/api'

The path in the URL where the microservice JSON RPC endpoint will be accessible.

MicroService.accessible_at = None

The url where the service can be accessed by other microservices. Useful when using a service registry.

Access validation

See also

Private methods

Event dispatching

MicroService.event_transports = []

A list of Event transports that will enable the Event dispatching feature.

See also

• Publisher-subscriber pattern
• Event transports

Dynamic configuration

MicroService.skip_configuration = False

Flag that if set to True, will disable the configurable sub-framework.

MicroService.configurables = [<Configurable name=port>, <Configurable name=host>, <Configurable name=accessible_at>, <Configurable name=endpoint>]

A list of configurable objects that allows the service’s running parameters to be changed dynamically without changing its code.

MicroService.configurators = [<CommandLineConfigurator>]

A list of configurator objects that will extract in order values for the defined configurators

See also

Configurables and configurators

Web application functionality

MicroService.extra_handlers = []

A list of extra Tornado handlers that will be included in the created Tornado application.

MicroService.template_dir = '.'

Template directory used by the created Tornado Application. Useful when you plan to add web application functionality to the microservice.

MicroService.static_dirs = []

A list of directories where the static files will looked for.

Periodic tasks

MicroService.periodic_tasks = []

A list of (callable, time_in_seconds) that will enable periodic task execution.

Service auto-discovery

MicroService.service_registry_urls = []

A list of service registry complete URL which will enable service auto-discovery.

MicroService.service_registry_ping_interval = 30

Interval (in seconds) when the microservice will ping all the service registries.

Misc

MicroService.max_parallel_blocking_tasks = 4

How many methods can be executed in parallel at the same time. Note that every blocking method is executed in a concurrent.features.ThreadPoolExecutor

Methods

Can be overridden

MicroService.on_service_start()

Override this method to do a set of actions when the service starts

Returns:None

MicroService.get_logger()

Override this method to designate the logger for the application

Returns:a logging.Logger instance

Can be called

MicroService.get_service(name)

Locates a remote service by name. The name can be a glob-like pattern ("project.worker.*"). If multiple services match the given name, a random instance will be chosen. There might be multiple services that match a given name if there are multiple services with the same name running, or when the pattern matches multiple different services.

Todo

Make this use self.io_loop to resolve the request. The current implementation is blocking and slow

Parameters:

name – a pattern for the searched service.

Returns:

a gemstone.RemoteService instance

Raises:

• ValueError – when the service can not be located
• ServiceConfigurationError – when there is no configured discovery strategy

MicroService.start_thread(target, args, kwargs)

Shortcut method for starting a thread.

Parameters:

• target – The function to be executed.
• args – A tuple or list representing the positional arguments for the thread.
• kwargs – A dictionary representing the keyword arguments.

New in version 0.5.0.

MicroService.emit_event(event_name, event_body, *, broadcast=True)

Publishes an event of type event_name to all subscribers, having the body event_body. The event is pushed through all available event transports.

The event body must be a Python object that can be represented as a JSON.

Parameters:

• event_name – a str representing the event type
• event_body – a Python object that can be represented as JSON.
• broadcast – flag that specifies if the event should be received by all subscribers or only by one

New in version 0.5.0.

Changed in version 0.10.0: Added parameter broadcast

MicroService.get_current_configuration()

MicroService.make_tornado_app()

Creates a :py:class`tornado.web.Application` instance that respect the JSON RPC 2.0 specs and exposes the designated methods. Can be used in tests to obtain the Tornado application.

Returns:a tornado.web.Application instance

MicroService.start()

The main method that starts the service. This is blocking.

class gemstone.RemoteService(service_endpoint, *, authentication_method=None)

Decorators

gemstone.exposed_method(name=None, private=False, is_coroutine=True, requires_handler_reference=False, **kwargs)

Marks a method as exposed via JSON RPC.

Parameters:

• name – the name of the exposed method. Must contains only letters, digits, dots and underscores. If not present or is set explicitly to None, this parameter will default to the name of the exposed method. If two methods with the same name are exposed, a ValueError is raised.
• public – Flag that specifies if the exposed method is public (can be accessed without token)
• private – Flag that specifies if the exposed method is private.
• is_coroutine – Flag that specifies if the method is a Tornado coroutine. If True, it will be wrapped with the tornado.gen.coroutine() decorator.
• kwargs – Not used.

New in version 0.9.0.

gemstone.event_handler(event_name)

Decorator for designating a handler for an event type. event_name must be a string representing the name of the event type.

The decorated function must accept a parameter: the body of the received event, which will be a Python object that can be encoded as a JSON (dict, list, str, int, bool, float or None)

Parameters:event_name – Returns:

gemstone.public_method(func)

Decorates a method to be exposed from a gemstone.PyMicroService concrete implementation. The exposed method will be public.

Deprecated since version 0.9.0: Use exposed_method() instead.

gemstone.private_api_method(func)

Decorates a method to be exposed (privately) from a gemstone.PyMicroService concrete implementation. The exposed method will be private.

Deprecated since version 0.9.0: Use exposed_method() instead.

gemstone.requires_handler_reference(func)

Marks a method tha requires access to the gemstone.TornadoJsonRpcHandler instance when calling the request. If a method is decorated with this, when it is called it will receive a handler argument as the first argument.

Useful when you need to do specific operations such as setting a cookie, setting a secure cookie, get the current_user of the request, etc.

Deprecated since version 0.9.0: Use exposed_method() instead.

Request handlers

class gemstone.GemstoneCustomHandler(*args, **kwargs)

Base class for custom Tornado handlers that can be added to the microservice.

Offers a reference to the microservice through the self.microservice attribute.

class gemstone.TornadoJsonRpcHandler(*args, **kwargs)

call_method(method)

Calls a blocking method in an executor, in order to preserve the non-blocking behaviour

If method is a coroutine, yields from it and returns, no need to execute in in an executor.

Parameters:method – The method or coroutine to be called (with no arguments). Returns:the result of the method call

handle_single_request(request_object)

Handles a single request object and returns the correct result as follows:

• A valid response object if it is a regular request (with ID)
• None if it was a notification (if None is returned, a response object with “received” body was already sent to the client.

Parameters:request_object – A gemstone.core.structs.JsonRpcRequest object representing a Request object Returns:A gemstone.core.structs.JsonRpcResponse object representing a Response object or None if no response is expected (it was a notification)

prepare_method_call(method, args)

Wraps a method so that method() will call method(*args) or method(**args), depending of args type

Parameters:

• method – a callable object (method)
• args – dict or list with the parameters for the function

Returns:

a ‘patched’ callable

write_single_response(response_obj)

Writes a json rpc response {"result": result, "error": error, "id": id}. If the id is None, the response will not contain an id field. The response is sent to the client as an application/json response. Only one call per response is allowed

Parameters:response_obj – A Json rpc response object Returns: