Skip to content

TRANSPORT.md

Latest commit

 

History

History
210 lines (127 loc) · 5.97 KB

TRANSPORT.md

File metadata and controls

210 lines (127 loc) · 5.97 KB

Transports

This version of mercure, in addition to the default bolt transport, implements the following transports: gdbm, redis, and postgres. Each of these transports provides a built-in cleanup routine which, when enabled, wakes up on predefined intervals and removes from the database events older than a certain timestamp. These two values - wake up interval and event time-to-live - are configured by the following parameters in the transport URL:

  • cleanup_interval= DURATION

Sets interval between two successive database cleanups. If not set, periodic database cleanup is disabled.

  • event_ttl= DURATION

Sets event time-to-live. Default is 24 hours.

The DURATION argument must be a valid input to time.ParseDuration.

For example, the following transport URL requires the use of redis database and performs database cleanup each 2 hours. During cleanup, events older than 12 hours are evicted:

   redis://hostname?cleanup_interval=2h&event_ttl=12h

The sections below discuss each transport type in detail

GDBM transport

This transport uses GNU dbm file storage. The URL has the form:

  gdbm://FILE[?PARAM]

where FILE is the database file name (either absolute, starting with a slash, or relative to the current working directory), and PARAM are database cleanup parameters.

Postgres transport

This transport uses a PostgreSQL database. The URL is a connection URI with optional cleanup parameters in its query part.

To use this transport follow the steps below:

  1. Create the database mercure and the user to access it.

  2. Connect to the database and create the table events:

CREATE TABLE events (
  id varchar(64) NOT NULL,
  ts timestamp NOT NULL DEFAULT NOW(),
  message text
);

CREATE UNIQUE INDEX event_id ON events (id);
CREATE INDEX event_ts ON events (ts);
  1. Configure the transport_url parameter (or MERCURE_TRANSPORT_URL environment variable, if using the mercure container), e.g. (assuming database name mercure, user name user and password guessme):
  transport_url "postgres://user:guessme@localhost/mercure&cleanup_interval=6h"

Redis transport

This transport uses a remote redis database. It requires Redis version 6.2.7 or newer.

To use redis database, you need to do the following.

  1. Start up a redis server

  2. In the mercure configuration, set the transport_url parameter to the URL of your server. If you are using mercure docker container, specify the URL in the MERCURE_TRANSPORT_URL environment variable.

URL

Redis database can be accessed via TCP/IP or via a UNIX socket. This is defined by the scheme part of the database URL. There are three possible URLs:

  • Plaintext TCP

     redis://[USER[:PASS]@]HOST:[PORT][/DBNUM][?PARAM]

  • TLS transport

     rediss://[USER[:PASS]@]HOST:[PORT][/DBNUM][?PARAM]

  • UNIX socket

     redis+unix://[USER[:PASS]@]PATH[?PARAM]

Common parts for all URLs are:

  • USER

User name.

  • PASS

User password.

  • HOST

Host name or IP address of the server running the redis server.

  • PORT

Port number to use. This defaults to 6379.

  • DBNUM

Number of the redis database to use.

  • PATH

Absolute pathname of the UNIX socket file.

  • PARAM

Additional parameters. These fall into two categories: Mercure-specific and generic Redis parameters.

Mercure-specific parameters

URL parameters specific for the mercure redis transport are cleanup parameters discussed above plus the following:

  • stream= NAME

Sets the name of the redis stream. Default value is mercure.

Generic Redis parameters

  • max_retries= INT

Maximum number of retries before giving up connection. This defaults to 3. The value of -1 disables retrying.

  • min_retry_backoff= DURATION

Minimum backoff interval between each retry. The value of this parameter must be a valid duration. The default is 8 milliseconds. -1 disables backoff.

  • max_retry_backoff= DURATION

Maximum backoff interval between each retry.

  • dial_timeout= DURATION

Dial timeout for establishing new connections. Default is 5 seconds.

  • read_timeout= DURATION

Timeout for socket reads. If reached, commands will fail with a timeout instead of blocking. The value -1 means no timeout. Default is 3 seconds.

  • write_timeout= DURATION

Timeout for socket writes. If reached, commands will fail with a timeout instead of blocking. Default is the value of read_timeout parameter.

  • pool_fifo= BOOL

Type of connection pool: true for FIFO, false (default) for LIFO.

  • pool_size= INT

Maximum number of socket connections. Default is 10 connections per every available CPU.

  • min_idle_conns= INT

Minimum number of idle connections which is useful when establishing new connection is slow.

  • max_conn_age= DURATION

Connection age at which client retires (closes) the connection. Default is to never close aged connections.

  • pool_timeout= DURATION

Amount of time client waits for connection if all connections are busy before returning an error. Default is read_timeout + 1 second.

  • idle_timeout= DURATION

Amount of time after which client closes idle connections. Should be less than server's timeout. Default is 5 minutes. -1 disables idle timeout check.

  • idle_check_frequency= DURATION

Frequency of idle checks made by idle connections reaper. Default is 1 minute. -1 disables idle connections reaper, but idle connections are still discarded by the client if idle_timeout is set.

  • read_only= BOOL

Enables read-only mode when querying slave nodes.