Cloud checks

The Check resource is a self-validation mechanism for cloud applications. Checks can be defined at any level and can be used to check if the system is healthy at that level.

Installation

npm i @winglibs/checks

Usage

For example, a check can query the HTTP API of an app to verify it's operational:

bring cloud;
bring http;
bring checks;

let api = new cloud.Api();

api.get("/", inflight (req) => {
  return { status: 200 };
});

new checks.Check(inflight () => { 
  assert(http.get(api.url).ok);
}) as "main route returns 200 ok";

The main route returns 200 ok check simply sends an HTTP GET to the url of the API and verifies that a success was returned.

There's a higher level convenience class called CheckHttp which can be used to implement this exact check:

new checks.CheckHttp(api.url) as "main route returns 200 ok";

As mentioned above, checks can be defined at the application level, but they can also be defined within user defined classes and shipped within Wing libraries. This turns them into a powerful mechanism for continuously making sure the system is healthy at multiple levels.

When do checks run?

Checks can be executed through any of these methods:

• By manually calling check.run()
• During deployment
• Periodically
• As a Wing test

Let's review each method.

Running checks manually with check.run()

The run() method will execute the check and will return the check results. If the check fails, run() will not throw an error, but the check result will have ok set to false and an error field.

Running checks during deployment

By default, all checks will run during deployment (using a cloud.OnDeploy resource). If a check fails, the deployment will fail as well.

To disable this behavior set deploy: false when the check is defined:

new Check(handler, deploy: false);

Running checks periodically

If you wish to run the check at a specific rate (e.g. as a health check), simply set the rate option to the desired rate:

new Check(handler, rate: 5m);

Running checks as tests

By default, all checks will also be executed as Wing tests.

For example, say we have failing.main.w:

let handler = inflight () => { assert(false); };
new cloud.Check(handler);

And then:

wing test failing.main.w

fail ┌ failing.main.wsim » root/env0/c.Check/test
     │ Error: assertion failed: false
     │     at /var/folders/vm/cm444l3124j_vh_8rkhz6kqm0000gn/T/wing-bundles-Vo5LLf/index.js:21:23
     │     at $Closure1.handle (/var/folders/vm/cm444l3124j_vh_8rkhz6kqm0000gn/T/wing-bundles-Vo5LLf/index.js:22:15)
     └     at exports.handler (/var/folders/vm/cm444l3124j_vh_8rkhz6kqm0000gn/T/wing-bundles-Vo5LLf/index.js:40:9)
 
 
Tests 1 failed (1)
Test Files 1 failed (1)
Duration 0m1.11s

If a check fails, the test will fail. To disable this behavior set testing to false:

let handler = inflight () => { assert(false); };
new cloud.Check(handler, testing: false);

Results

When a check is run, the result of a check is stored and includes the following fields:

• timestamp in UTC
• ok status
• error message (only if the check failed)
• checkid the unique id of the check (non human readable)
• checkpath the node path of the check (human readable)

To obtain the result of the last run, use the check.latest() method, which returns an optional CheckResult. If the test was never executed, nil is returned.

The check results of the entire app are stored in a shared bucket and can be obtained through this api:

bring checks;
let resultsBucket = checks.Results.getOrCreate(this).bucket;
let allResults = resultsBucket.list();

Roadmap

• Centrally enable/disable checks either only in deploy-time or always.
• REST API for querying/executing checks
• Console UI

Maintainers

• Elad Ben-Israel
• Subhodip Roy

License

Licensed under the MIT License.

API Reference

Table of Contents

• Classes
  • Results
  • Check
  • CheckHttp
• Interfaces
  • ICheck
• Structs
  • CheckResult
  • CheckProps
  • CheckHttpProps

Results (preflight class)

No description

Constructor

new(): Results

Properties

No properties

Methods

Signature	Description
inflight latest(checkid: str): CheckResult?	No description
static of(scope: IResource): Results	No description
inflight store(result: CheckResult): void	No description

Check (preflight class)

No description

Constructor

new(handler: inflight (): void, props: CheckProps?): Check

Properties

No properties

Methods

Signature	Description
inflight latest(): CheckResult?	No description
inflight run(): CheckResult	No description

CheckHttp (preflight class)

No description

Constructor

new(url: str, options: CheckHttpProps?): CheckHttp

Properties

No properties

Methods

Signature	Description
inflight latest(): CheckResult?	No description
inflight run(): CheckResult	No description

ICheck (interface)

No description

Properties

No properties

Methods

Signature	Description
inflight latest(): CheckResult?	No description
inflight run(): CheckResult	No description

CheckResult (struct)

No description

Properties

Name	Type	Description
checkid	str	No description
checkpath	str	No description
error	str?	No description
ok	bool	No description
timestamp	str	No description

CheckProps (struct)

No description

Properties

Name	Type	Description
deploy	bool?	No description
rate	duration?	No description
testing	bool?	No description

CheckHttpProps (struct)

No description

Properties

Name	Type	Description
body	str?	No description
deploy	bool?	No description
method	HttpMethod?	No description
path	str?	No description
rate	duration?	No description
status	num?	No description
testing	bool?	No description