Built-in Extensions

Nameko includes a number of built-in extensions. This section introduces them and gives brief examples of their usage.


Nameko includes an implementation of RPC over AMQP. It comprises the @rpc entrypoint, a proxy for services to talk to other services, and a standalone proxy that non-Nameko clients can use to make RPC calls to a cluster:

from nameko.rpc import rpc, RpcProxy

class ServiceY:
    name = "service_y"

    def append_identifier(self, value):
        return u"{}-y".format(value)

class ServiceX:
    name = "service_x"

    y = RpcProxy("service_y")

    def remote_method(self, value):
        res = u"{}-x".format(value)
        return self.y.append_identifier(res)
from nameko.standalone.rpc import ClusterRpcProxy

config = {
    'AMQP_URI': AMQP_URI  # e.g. "pyamqp://guest:guest@localhost"

with ClusterRpcProxy(config) as cluster_rpc:
    cluster_rpc.service_x.remote_method("hellø")  # "hellø-x-y"

Normal RPC calls block until the remote method completes, but proxies also have an asynchronous calling mode to background or parallelize RPC calls:

with ClusterRpcProxy(config) as cluster_rpc:
    hello_res = cluster_rpc.service_x.remote_method.call_async("hello")
    world_res = cluster_rpc.service_x.remote_method.call_async("world")
    # do work while waiting
    hello_res.result()  # "hello-x-y"
    world_res.result()  # "world-x-y"

In a cluster with more than one instance of the target service, RPC requests round-robin between instances. The request will be handled by exactly one instance of the target service.

AMQP messages are ack’d only after the request has been successfully processed. If the service fails to acknowledge the message and the AMQP connection is closed (e.g. if the service process is killed) the broker will revoke and then allocate the message to the available service instance.

Request and response payloads are serialized into JSON for transport over the wire.

Events (Pub-Sub)

Nameko Events is an asynchronous messaging system, implementing the Publish-Subscriber pattern. Services dispatch events that may be received by zero or more others:

from nameko.events import EventDispatcher, event_handler
from nameko.rpc import rpc

class ServiceA:
    """ Event dispatching service. """
    name = "service_a"

    dispatch = EventDispatcher()

    def dispatching_method(self, payload):
        self.dispatch("event_type", payload)

class ServiceB:
    """ Event listening service. """
    name = "service_b"

    @event_handler("service_a", "event_type")
    def handle_event(self, payload):
        print("service b received:", payload)

The EventHandler entrypoint has three handler_types that determine how event messages are received in a cluster:

  • SERVICE_POOL – event handlers are pooled by service name and one instance from each pool receives the event, similar to the cluster behaviour of the RPC entrypoint. This is the default handler type.
  • BROADCAST – every listening service instance will receive the event.
  • SINGLETON – exactly one listening service instance will receive the event.

An example of using the BROADCAST mode:

from nameko.events import BROADCAST, event_handler

class ListenerService:
    name = "listener"

        "monitor", "ping", handler_type=BROADCAST, reliable_delivery=False
    def ping(self, payload):
        # all running services will respond
        print("pong from {}".format(self.name))

Events are serialized into JSON for transport over the wire.


The HTTP entrypoint is built on top of werkzeug, and supports all the standard HTTP methods (GET/POST/DELETE/PUT etc)

The HTTP entrypoint can specify multiple HTTP methods for a single URL as a comma-separated list. See example below.

Service methods must return one of:

  • a string, which becomes the response body
  • a 2-tuple (status code, response body)
  • a 3-tuple (status_code, headers dict, response body)
  • an instance of werkzeug.wrappers.Response
# http.py

import json
from nameko.web.handlers import http

class HttpService:
    name = "http_service"

    @http('GET', '/get/<int:value>')
    def get_method(self, request, value):
        return json.dumps({'value': value})

    @http('POST', '/post')
    def do_post(self, request):
        return u"received: {}".format(request.get_data(as_text=True))

    @http('GET,PUT,POST,DELETE', '/multi')
    def do_multi(self, request):
        return request.method
$ nameko run http
starting services: http_service
$ curl -i localhost:8000/get/42
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 13
Date: Fri, 13 Feb 2015 14:51:18 GMT

{'value': 42}
$ curl -i -d "post body" localhost:8000/post
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 19
Date: Fri, 13 Feb 2015 14:55:01 GMT

received: post body

A more advanced example:

# advanced_http.py

from nameko.web.handlers import http
from werkzeug.wrappers import Response

class Service:
    name = "advanced_http_service"

    @http('GET', '/privileged')
    def forbidden(self, request):
        return 403, "Forbidden"

    @http('GET', '/headers')
    def redirect(self, request):
        return 201, {'Location': 'https://www.example.com/widget/1'}, ""

    @http('GET', '/custom')
    def custom(self, request):
        return Response("payload")
$ nameko run advanced_http
starting services: advanced_http_service
$ curl -i localhost:8000/privileged
Content-Type: text/plain; charset=utf-8
Content-Length: 9
Date: Fri, 13 Feb 2015 14:58:02 GMT
curl -i localhost:8000/headers
Location: https://www.example.com/widget/1
Content-Type: text/plain; charset=utf-8
Content-Length: 0
Date: Fri, 13 Feb 2015 14:58:48 GMT

You can control formatting of errors returned from your service by overriding response_from_exception():

import json
from nameko.web.handlers import HttpRequestHandler
from werkzeug.wrappers import Response
from nameko.exceptions import safe_for_serialization

class HttpError(Exception):
    error_code = 'BAD_REQUEST'
    status_code = 400

class InvalidArgumentsError(HttpError):
    error_code = 'INVALID_ARGUMENTS'

class HttpEntrypoint(HttpRequestHandler):
    def response_from_exception(self, exc):
        if isinstance(exc, HttpError):
            response = Response(
                    'error': exc.error_code,
                    'message': safe_for_serialization(exc),
            return response
        return HttpRequestHandler.response_from_exception(self, exc)

http = HttpEntrypoint.decorator

class Service:
    name = "http_service"

    @http('GET', '/custom_exception')
    def custom_exception(self, request):
        raise InvalidArgumentsError("Argument `foo` is required.")
$ nameko run http_exceptions
starting services: http_service
$ curl -i http://localhost:8000/custom_exception
Content-Type: application/json
Content-Length: 72
Date: Thu, 06 Aug 2015 09:53:56 GMT

{"message": "Argument `foo` is required.", "error": "INVALID_ARGUMENTS"}

You can change the HTTP port and IP using the WEB_SERVER_ADDRESS config setting:

# foobar.yaml

AMQP_URI: 'pyamqp://guest:guest@localhost'


The Timer is a simple entrypoint that fires once per a configurable number of seconds. The timer is not “cluster-aware” and fires on all services instances.

from nameko.timer import timer

class Service:
    name ="service"

    def ping(self):
        # method executed every second