Documentation
code/hello-world/ $ tomodachi run service/app.py

Options / config parameters

A tomodachi.Service extended service class may specify a class attribute named options (as a dict) for additional configuration.

import json

import tomodachi


class Service(tomodachi.Service):
    name = "http-example"

    options = {
        "http.port": 80,
        "http.content_type": "application/json; charset=utf-8",
        "http.real_ip_from": [
            "127.0.0.1/32", 
            "10.0.0.0/8", 
            "172.16.0.0/12", 
            "192.168.0.0/16",
        ],
        "http.keepalive_timeout": 5,
        "http.max_keepalive_requests": 20,
        "watcher.ignored_dirs": ["node_modules"],
    }

    @tomodachi.http("GET", r"/health")
    async def health_check(self, request):
        return 200, json.dumps({"status": "healthy"})

    # Specify custom 404 catch-all response
    @tomodachi.http_error(status_code=404)
    async def error_404(self, request):
        return json.dumps({"error": "not-found"})

Here follows a table of available config parameters that can be applied as options.

Configuration key

Description

Default value

http.port

TCP port (integer value) to listen for incoming connections.

9700

http.host

Network interface to bind TCP server to. "0.0.0.0" will bind to all IPv4 interfaces. None or "" will assume all network interfaces.

"0.0.0.0"

http.reuse_port

If set to True (which is also the default value on Linux) the HTTP server will bind to the port using the socket option SO_REUSEPORT. This will allow several processes to bind to the same port, which could be useful when running services via a process manager such as supervisord or when it's desired to run several processes of a service to utilize additional CPU cores, etc. Note that the reuse_port option cannot be used on non-Linux platforms.

True on Linux, otherwise False

http.keepalive_timeout

Enables connections to use keep-alive if set to an integer value over 0. Number of seconds to keep idle incoming connections open.

0

http.max_keepalive_requests

An optional number (integer value) of requests which is allowed for a keep-alive connection. After the specified number of requests has been done, the connection will be closed. An option value of 0 or None (default) will allow any number of requests over an open keep-alive connection.

None

http.max_keepalive_time

An optional maximum time in seconds (int) for which keep-alive connections are kept open. If a keep-alive connection has been kept open for more than http.max_keepalive_time seconds, the following request will be closed upon returning a response. The feature is not used by default and won't be used if the value is 0 or None. A keep-alive connection may otherwise be open unless inactive for more than the keep-alive timeout.

None

http.client_max_size

The client’s maximum size in a request, as an integer, in bytes.

(1024 ** 2) * 100

http.termination_grace_period_seconds

The number of seconds to wait for functions called via HTTP to gracefully finish execution before terminating the service, for example if service received a SIGINT or SIGTERM signal while requests were still awaiting response results.

30

http.real_ip_header

Header to read the value of the client's real IP address from if service operates behind a reverse proxy. Only used if http.real_ip_from is also set and the proxy's IP correlates with a value in http.real_ip_from.

"X-Forwarded-For"

http.real_ip_from

IP address(es) or IP subnet(s) / CIDR. Allows the http.real_ip_header header value to be used as client's IP address if connecting reverse proxy's IP matches a value in the list or is within a specified subnet. For example ["127.0.0.1/32", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] would permit header to be used if closest reverse proxy is "127.0.0.1" or within the three common private network IP address ranges.

[]

http.content_type

Default content-type header to use if not specified in the response.

"text/plain; charset=utf-8"

http.access_log

If set to the default value (boolean) True, the HTTP access log will be printed to stdout (using logger transport.http). If set to a string value, the access log will additionally also be stored to file using the value as filename / file path.

True

http.server_header

"Server" header value in responses.

"tomodachi"

… …

aws_sns_sqs.region_name

The AWS region to use for SNS+SQS pub/sub API requests.

None

aws_sns_sqs.aws_access_key_id

The AWS access key to use for SNS+SQS pub/sub API requests.

None

aws_sns_sqs.aws_secret_access_key

The AWS secret to use for SNS+SQS pub/sub API requests.

None

aws_sns_sqs.topic_prefix

A prefix to any SNS topics used. Could be good to differentiate between different dev environments.

""

aws_sns_sqs.queue_name_prefix

A prefix to any SQS queue names used. Could be good to differentiate between different dev environments.

""

aws_sns_sqs.sns_kms_master_key_id

If set, will set the KMS key (alias or id) to use for encryption at rest on the SNS topics created by the service or subscribed to by the service. Note that an option value set to an empty string ("") or False will unset the KMS master key id and thus disable encryption at rest. If instead an option is completely unset or set to None value no changes will be done to the KMS related attributes on an existing topic.

None (no changes to KMS settings)

aws_sns_sqs.sqs_kms_master_key_id

If set, will set the KMS key (alias or id) to use for encryption at rest on the SQS queues created by the service or for which the service consumes messages on. Note that an option value set to an empty string ("") or False will unset the KMS master key id and thus disable encryption at rest. If instead an option is completely unset or set to None value no changes will be done to the KMS related attributes on an existing queue.

None (no changes to KMS settings)

aws_sns_sqs.sqs_kms_data_key_reuse_period

If set, will set the KMS data key reuse period value on the SQS queues created by the service or for which the service consumes messages on. If the option is completely unset or set to None value no change will be done to the KMSDataKeyReusePeriod attribute of an existing queue, which can be desired if it's specified during deployment, manually or as part of infra provisioning. Unless changed, SQS queues using KMS use the default value 300 (seconds).

None (no changes to attribute)

… …

aws_endpoint_urls.sns

Configurable endpoint URL for AWS SNS – primarily used for testing during development using fake services / fake endpoints.

None

aws_endpoint_urls.sqs

Configurable endpoint URL for AWS SQS – primarily used for testing during development using fake services / fake endpoints.

None

… …

amqp.host

Host address / hostname for RabbitMQ server.

"127.0.0.1"

amqp.port

Host post for RabbitMQ server.

5672

amqp.login

Login credentials.

"guest"

amqp.password

Login credentials.

"guest"

amqp.exchange_name

The AMQP exchange name to use in the service.

"amq.topic"

amqp.routing_key_prefix

A prefix to add to any AMQP routing keys provided in the service.

""

amqp.queue_name_prefix

A prefix to add to any AMQP queue names provided in the service.

""

amqp.virtualhost

AMQP virtualhost settings.

"/"

amqp.ssl

TLS can be enabled for supported host connections.

False

amqp.heartbeat

The heartbeat timeout value defines after what period of time the peer TCP connection should be considered unreachable (down) by RabbitMQ and client libraries.

60

amqp.queue_ttl

TTL set on newly created queues.

86400

… …

watcher.ignored_dirs

Directories / folders that the automatic code change watcher should ignore. Could be used during development to save on CPU resources if any project folders contains a large number of file objects that doesn't need to be watched for code changes. Already ignored directories are "__pycache__", ".git", ".svn", "__ignored__", "__temporary__" and "__tmp__".

[]

watcher.watched_file_endings

Additions to the list of file endings that the watcher should monitor for file changes. Already followed file endings are ".py", ".pyi", ".json", ".yml", ".html" and ".phtml".

[]

… …

___________________________