Skip to main content

Microcosm - Simple microservice configuration

Project description

Simple Microservice Configuration

Well-written microservices are small and single-purpose; any non-trivial ecosystem will have a fleet of such services, each performing a different function. Inevitably, these services will use common code and structure; this library provides a simple mechanism for constructing these shared components and wiring them together into services.

Circle CI

Terminology

  • A microservice is a small software application. It is composed of several smaller pieces of software, many of which are reusable.
  • A component is one of these (possibly reusable) pieces of software.
  • A factory is a function used to create a component; it may be an object's constructor.
  • A config dict is a nested dictionary with string-valued keys. It contains data used by factories to create components.
  • An object graph is a collection of components that may reference each other (acyclically).
  • A binding is a string-valued key. It is used to identify a component within an object graph and the subsection of the config dict reserved for a component's factory.

Basic Usage

  1. Define factory functions for components, attach them to a binding, and provide (optional) configuration defaults:

    from microcosm.api import defaults, binding
    
    @binding("foo")
    @defaults(baz="value")
    def create_foo(graph):
        return dict(
            # factories can reference other components
            bar=graph.bar,
            # factories can reference configuration
            baz=graph.config.foo.baz,
        )
    
    @binding("bar")
    def create_bar(graph):
        return dict()
    

    Factory functions have access to the object graph and, through it, the config dict. Default configuration values, if provided, are pre-populated within the provided binding; these may be overridden from data loaded from an external source.

  2. Wire together the microservice by creating a new object graph along with service metadata:

    from microcosm.api import create_object_graph
    
    graph = create_object_graph(
        name="myservice",
        debug=False,
        testing=False,
    )
    

    Factories may access the service metadata via graph.metadata. This allows for several best practices:

    • Components can implement ecosystem-wide conventions (e.g. for logging or persistence), using the service name as a discriminator.
    • Components can customize their behavior during development (debug=True) and unit testing (testing=True)
  3. Reference any binding in the object graph to access the corresponding component:

    print(graph.foo)
    

    Components are initialized lazily. In this example, the first time graph.foo is accessed, the bound factory (create_foo()) is automatically invoked. Since this factory in turn accesses graph.bar, the next factory in the chain (create_bar()) would also be called if it had not been called yet.

    Graph cycles are not allowed, although dependent components may cache the graph instance to access depending components after initialization completes.

  4. Optionally, initialize the microservice's components explicitly:

    graph.use(
        "foo",
        "bar",
    )
    

    While the same effect could be achieved by accessing graph.foo or graph.bar, this construction has the advantage of initializes the listed components up front and triggering any configuration errors as early as possible.

    It is also possible to then disable any subsequent lazy initialization, preventing any unintended initialization during subsequent operations:

    graph.lock()
    

Assumptions

This library was influenced by the pinject project, but makes a few assumption that allow for a great deal of simplication:

  1. Microservices are small enough that simple string bindings suffice. Or, put another way, conflicts between identically bound components are a non-concern and there is no need for explicit scopes.

  2. Microservices use processes, not threads to scale. As such, thread synchronization is a non-goal.

  3. Mocking (and patching) of the object graph is important and needs to be easy. Unit tests expect to use `unittest.mock library; it should be trivial to temporarily replace a component.

  4. Some components will be functions that modify other components rather than objects that need to be instantiated.

Setup

Create a virtualenv

python -m venv venv
. ./venv/bin/activate

Install dependencies

pip install -U -e .

Tests

Run the tests

python setup.py nosetests

Lint

Lint the code:

NAME=microcosm ./entrypoint.sh lint
NAME=microcosm ./entrypoint.sh typehinting

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

microcosm-4.1.0.tar.gz (25.1 kB view details)

Uploaded Source

Built Distribution

microcosm-4.1.0-py3-none-any.whl (30.7 kB view details)

Uploaded Python 3

File details

Details for the file microcosm-4.1.0.tar.gz.

File metadata

  • Download URL: microcosm-4.1.0.tar.gz
  • Upload date:
  • Size: 25.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.9

File hashes

Hashes for microcosm-4.1.0.tar.gz
Algorithm Hash digest
SHA256 2d9297ffdd296d4ca96c81b6c96db6dfe89bf71371d5abf58865a0b699852279
MD5 57fb85d77845bcdadcfa3ef2fb7eefdb
BLAKE2b-256 2311f1badbae3dc6ef64316ba6f00481a0a44d7515c3c560546964341eb4235e

See more details on using hashes here.

File details

Details for the file microcosm-4.1.0-py3-none-any.whl.

File metadata

  • Download URL: microcosm-4.1.0-py3-none-any.whl
  • Upload date:
  • Size: 30.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.9

File hashes

Hashes for microcosm-4.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f85d7f60a388b5a2d59083c0fd5e9c120c44bfb3a779d62d1094f1bc37d6fae0
MD5 c649b6faccfbd9a852553e389b7407db
BLAKE2b-256 6b469a113fa4b6412a170333c566707db642095c45a60eb2c1ea618e846d4c37

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page