await

README

await

Await availability of resources.

This can be useful in the context of Docker Compose where a service needs to wait for other dependent services.

Optionally a timeout can be provided to specify how long to wait for all dependent resources to become available. On success the command returns code 0, on failure it returns code 1.

Additionally, a command can be specified which gets executed after all dependent resources became available.

History

This repository is a fork of Betalo's await. Since the company decided to no longer support it, I forked it and started adding features myself. This repository will only contain versions 1.2 and above due to that.

Installation

go get -u github.com/fcristovao/await

or

curl -s -f -L -o await https://github.com/fcristovao/await/releases/download/v1.3.0/await-linux-amd64
chmod +x await

Usage

$ await -h
Usage: await [options...] <res>... [ -- <cmd>]
Await availability of resources.

  -V	Show version
  -f	Force running the command even after giving up
  -i string
    	Read resources from file, '-' to read from stdin
  -q	Set quiet mode
  -t duration
    	Set timeout duration before giving up (default 1m0s)
  -v	Set verbose output mode
  -vv
    	Set more verbose output mode

Resources

All dependent resources must be specified as URLs or escaped command.

Some resources provided additional functionally encoded as fragment (#<fragment>). The syntax follows the URL query syntax: k1|k1=|k1=v1,v2,v3...[&k2=v1&...]. E.g.: http://example.com/#ssl&foo=bar,baz&i=j

Valid resources are: HTTP, Websocket, TCP, File, PostgreSQL, MySQL, Kafka and Command.

HTTP Resource

Availability: Available when a connection to a given server is established and an empty request returns the response status code is 2xx. Unavailable otherwise.

URL syntax: http[s]://[<user>[:<pass>]@]<host>[:<port>][<path>][?<query>][#<fragment>]

Fragment:

• tls=skip-verify: When used, it skips TLS check for https resources.

Websocket Resource

Availability: Available when a connection to a given server is established. Unavailable otherwise.

URL syntax: ws[s]://[<user>[:<pass>]@]<host>[:<port>][<path>][?<query>]

TCP Resource

Availability: Available when a connection to a given server is established. Unavailable otherwise.

URL syntax: tcp[4|6]://<host>:<port>

File Resource

Availability: Available when given path is a file and the file exists or, if declared absent, the file does not exist. Unavailable otherwise.

URL syntax: file://<path>[#<fragment>]

• absent key: If present, the resource is defined as available, when the specific file is absent, rather than existing.

PostgreSQL Resource

Availability: Available when a connection to a given PostgreSQL database server is established and optional a given database could be found and optional any tables or a set of tables could be found. Unavailable otherwise.

URL syntax: postgres://[<user>[:<pass>]@]<host>[:<port>][/<dbname>][?<dbparams>][#<fragment>]

The URL defines a DSN.

The database name <dbname> is optional. If provided, the resource is classified as available as soon as the database was found.

DB Parameters:

• sslmode=[verify-ca|require]: sslmode=verify-ca enables TLS/SSL encrypted connection to the server. Use sslmode=require if you want to use a self-signed or invalid certificate (server side). See lib/pq for more details.

Fragment:

• tables[=t1,t2,...] key-value: If key present and value absent, the resource's database scheme must at least contain one table. If key present and value present, the resource's database scheme must at least contain the specified tables. Using this key requires to provide a database name.

MySQL Resource

Availability: Available when a connection to a given MySQL database server is established and optional a given database could be found and optional any tables or a set of tables could be found. Unavailable otherwise.

URL syntax: mysql://[<user>[:<pass>]@]<host>[:<port>][/<dbname>][?<dbparams>][#<fragment>]

The URL defines a DSN.

The database name <dbname> is optional. If provided, the resource is classified as available as soon as the database was found.

DB Parameters:

• tls=[true|skip-verify]: tls=true enables TLS/SSL encrypted connection to the server. Use tls=skip-verify if you want to use a self-signed or invalid certificate (server side). See go-sql-driver/mysql for more details.

Fragment:

• tables[=t1,t2,...] key-value: If key present and value absent, the resource's database scheme must at least contain one table. If key present and value present, the resource's database scheme must at least contain the specified tables. Using this key requires to provide a database name.

AMQP resource

Availability: Available when a connection to the given AMQP server is established. Unavailable otherwise.

URL syntax: amqp[s]://[<user>[:<pass>]@]<host>[:<port>]/[<vhost>]

Kafka Resource

Availability: Available when a connection to a given Kafka broker is established and, optionally, a set of topics could be found. Unavailable otherwise.

URL syntax: kafka[s]://[<user>[:<pass>]@]<host>[:<port>][#<fragment>]

Using kafkas scheme enables TLS/SSL encrypted connection to the server.

If no port is set, 9092 will be used as default for kafka scheme, or 9093 for kafkas scheme.

Fragment:

• topics[=t1,t2,...]: If topics present but with no values, the resource's broker must at least contain one topic. If topics present with values set, the resource's broker must at least contain the specified topics (comma-separated names).

• tls=skip-verify: When used, it skips TLS check for kafkas resources.

• sasl=[plain|scram-sha-256|scram-sha-512]: Only relevant when setting username and password. Default is plain. See Kafka's SASL configuration and Kafka's SASL SCRAM configuration for more details.

Command Resource

Does not follow the URL syntax and is used as generic fallback for invalid URLs (i.e. schema is absent).

Availability: Available when command return status code 0. Unavailable otherwise.

URL syntax: <path> [<arg>...]

Alternatives

Once Docker-Compose support the Docker HEALTHCHECK directive for awaiting services being up, this tool could become deprecated.

Many alternative solutions exist, most of them avoiding to interpret the resource type, leaving only options like tcp and http, or having a specific focus on Docker Compose. A few of them listed below:

• ContainerPilot
• controlled-compose
• crane
• docker-wait
• dockerize
• wait-for-it
• wait_for_db
• wait_to_start.sh
• waitforservices

License

MIT License. See LICENSE.

Documentation

Overview

Copyright (C) 2016-2018 Betalo AB

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.