watchbot

0.0.5

watchbot

Watchbot's JavaScript API

Static members

.messages(queue, topic, stackName, backoff)

Creates messages objects

messages(queue, topic, stackName, backoff)

Creates messages objects

Parameters

  • string queue :

    the URL of an SQS queue

  • string topic :

    the ARN of an SNS topic for failure notifications

  • string stackName :

    the name of the CloudFormation stack

  • boolean backoff :

    whether jobs retrying should be returned to SQS with exponential backoff.

Returns

object :

a messages object

.tasks(cluster, taskDefinition, containerName, concurrency)

Creates tasks objects

tasks(cluster, taskDefinition, containerName, concurrency)

Creates tasks objects

Parameters

  • string cluster :

    the ARN of the ECS cluster to run tasks on

  • string taskDefinition :

    the ARN of the processing TaskDefinition to run

  • string containerName :

    the name of the container defined by the TaskDefinition

  • number concurrency :

    the desired task concurrency

Returns

object :

a tasks object

.notifications(topic)

Creates notifications objects

notifications(topic)

Creates notifications objects

Parameters

  • string topic :

    the ARN of an SNS topic to receive notifications

Returns

object :

an notifications object

.main(config)

The main Watchbot loop

main(config)

The main Watchbot loop

Parameters

  • object config :

    configuration parameters

    • string config.NotificationTopic

      the ARN for the notification SNS topic

    • string config.Cluster

      the ARN for the ECS cluster

    • string config.TaskDefinition

      the ARN for the worker task definition

    • string config.ContainerName

      the name of the container defined by the TaskDefinition

    • number config.Concurrency

      the number of concurrent tasks

    • string config.QueueUrl

      the URL for the SQS queue

    • string config.StackName

      the name of the CFN stack

    • boolean config.ExponentialBackoff

      whether to retry with backoff

    • string = config.LogLevel (default info)

      fastlog log level

Returns

object :

an event emitter that will emit an finish event if the main loop is stopped.

Static members

.end

Signals the main loop to shut down.

end

Signals the main loop to shut down.

.log(msg, subst1)

Writes logs to stdout prefixed with a timestamp, category, and message id. Usage is identical to console.log

log(msg, subst1)

Writes logs to stdout prefixed with a timestamp, category, and message id. Usage is identical to console.log

Parameters

  • string msg :

    a string containing one or more substition strings

  • string subst1 :

    strings with which to replace substitution strings within msg

.template(options)

Creates a bare-bones CloudFormation template for a Watchbot stack

template(options)

Creates a bare-bones CloudFormation template for a Watchbot stack

Parameters

  • object options :

    configuration details

    • string options.description

      a description to set for the template

    • boolean options.provideUser

      set to true to provide a keypair with permission to send work to the queue.

    • boolean options.useWebhooks

      set to true to enable a webhook endpoint allowing an HTTPS POST request to add work to the queue.

    • boolean options.useWebhookKey

      require an API key in order to POST to the webhook endpoint

    • object options.taskEnv

      a set of key-value pairs to provide as environment variables to all tasks.

Returns

object :

a CloudFormation template. JSON.stringify this object and save it to a file in order to deploy the stack.

messages

An SQS message tracker

Static members

.complete(finishedTask, callback)

Handle a completed SQS message

complete(finishedTask, callback)

Handle a completed SQS message

Parameters

  • object finishedTask :

    a fainishedTask object defining the task outcome

  • function callback :

    a function called when the finished job has been handled appropriately

.poll(max, callback)

Poll SQS to find jobs

poll(max, callback)

Poll SQS to find jobs

Parameters

  • number max :

    the maximum number of jobs to take from the queue (max 10)

  • function callback :

    a function called after polling completes. The callback will be provided with an object of key-value object pairs representing environment variables (see environment) to be provided to a task

environment

Environment variables providing SQS message details to the processing task

Properties

  • string MessageId :

    the SQS MessageId

  • string Subject :

    the message's subject

  • string Message :

    the message's body

  • string SentTimestamp :

    the time the message was sent

  • string ApproximateFirstReceiveTimestamp :

    the time the message was first received

  • string ApproximateReceiveCount :

    the number of times the message has been received

tasks

An ECS task runner and status tracker

Static members

.outcome

Possible task outcomes

outcome

Possible task outcomes

Properties

  • string success :

    indicates that the container(s) provided an exit code 0. The SQS message should be deleted.

  • string fail :

    indicates that the container(s) provided an exit code 3. The SQS message should be deleted and a notification sent.

  • string noop :

    indicates that the container(s) provided an exit code 3. The SQS message should be deleted and a notification sent.

  • string retry :

    indicates that container(s) provided an unknown or mismatched exit code. The SQS message should be returned and a notification sent.

.poll(callback)

Checks the status of all pending tasks

poll(callback)

Checks the status of all pending tasks

Parameters

  • function callback :

    a function to handle the response. Will be provided a taskStatus object.

.run(env, callback)

Runs a task if currently below desired concurrency

run(env, callback)

Runs a task if currently below desired concurrency

Parameters

  • object env :

    key-value pairs of environment variables to provide to the task

  • function callback :

    a function to run when the task has been started. An error object with code AboveConcurrency indicates that there are already the maximum number of concurrent tasks running.

taskStatus

An array of finishedTask objects

Properties

  • number free :

    the difference between current and maximum desired task concurrency.

finishedTask

An object providing information about the outcome of a task

Properties

  • object arns :

    indentifiers for resources involved in running the task

    • arns.cluster string

      the ECS cluster's ARN

    • arns.instance string

      the EC2's ARN (use in ecs.describeContainerInstances requests)

    • arns.task string

      the tasks ARN (use in ecs.describeTasks requests)

  • string reason :

    the ECS-provided reason that the task ended

  • object env :

    key-value pairs indicating the task's environment variables

  • string outcome :

    one of the outcomes defined by tasks.outcome

notifications

An notifications object

Static members

.send(subject, message, callback)

Send a notification to the SNS topic

send(subject, message, callback)

Send a notification to the SNS topic

Parameters

  • string subject :

    the subject of the message

  • string message :

    the body of the message

  • function callback :

    a function to call when the notification has been sent