delay

README

delay

NOTE: This is not an official Google project. It's an experimental derivative of the google.golang.org/appengine/delay package. Where that package is intended for App Engine applications, this package is intended to be used with Cloud Run.

---

delay is a package that attempts to bring the simplicity of google.golang.org/appengine/delay to Cloud Run apps, to make it simpler to enqueue work to be handled later using Cloud Tasks.

Prerequisites

You must create the Task Queue yourself, which requires creating an App Engine application. That application and region must match the region where the Cloud Run service is deployed.

Usage

First, register your handler function. This must be done at init-time.

import "github.com/imjasonh/delay/"

var laterFunc = delay.Func(myFunc)

You can also use a function literal:

var laterFunc = delay.Func(func(ctx context.Context, some, args string) error {
	...
})

Before calling the function you should also initialize the package:

func init() {
	delay.Init()
}

Then, to call the function, invoke its Call method.

err := laterFunc.Call(ctx, req, queueName, "arg1", "arg2", "arg3")

Each time the function is invoked, a Cloud Task will be enqueued which will be handled by the specified handler function.

You can also schedule invocation for a time in the future with laterFunc.Delay, specifying a duration to wait. This instructs the Cloud Tasks queue to invoke the function at a time in the future.

Documentation

Overview

Package delay provides a way to execute code outside the scope of a user request by using the Cloud Tasks API.

To declare a function that may be executed later, call Func in a top-level assignment context, passing it a function whose first argument is of type context.Context.

var laterFunc = delay.Func(myFunc)

It is also possible to use a function literal.

var laterFunc = delay.Func(func(ctx context.Context, x string) {
	// ...
})

To call a function, invoke its Call method.

err = laterFunc.Call(ctx, req, queueName, "something", 42, 3.14)

To call a function after a delay, invoke its Delay method.

err = laterFunc.Delay(ctx, req, queueName, time.Minute, "something", 42, 3.14)

A function may be called any number of times. If the function has any return arguments, and the last one is of type error, the function may return a non-nil error to signal that the function failed and should be retried. Other return values are ignored.

The arguments to functions may be of any type that is encodable by the gob package. If an argument is of interface{} type, it is the client's responsibility to register with the gob package whatever concrete type may be passed for that argument; see http://golang.org/pkg/gob/#Register for details.

Any errors during initialization or execution of a function will be logged to the application logs. Error logs that occur during initialization will be associated with the request that invoked the Call method.

The state of a function invocation that has not yet successfully executed is preserved by combining the file name in which it is declared with the string key that was passed to the Func function. Updating an app with pending function invocations should safe as long as the relevant functions have the (filename, key) combination preserved. The filename is parsed according to these rules:

• Paths in package main are shortened to just the file name (github.com/foo/foo.go -> foo.go)
• Paths are stripped to just package paths (/go/src/github.com/foo/bar.go -> github.com/foo/bar.go)
• Module versions are stripped (/go/pkg/mod/github.com/foo/bar@v0.0.0-20181026220418-f595d03440dc/baz.go -> github.com/foo/bar/baz.go)

The delay package uses the Cloud Tasks API to create tasks that call the reserved application path "/internal/queue/go/delay".

Index

• func Init()
• type Function
  • func Func(i interface{}) *Function
  • func (f *Function) Call(ctx context.Context, req *http.Request, queueName string, args ...interface{}) error
  • func (f *Function) Delay(ctx context.Context, req *http.Request, queueName string, delay time.Duration, ...) error
• type Meta
  • func MetaFromContext(ctx context.Context) Meta

Functions

func Init

func Init()

Types

type Function

type Function struct {
	// contains filtered or unexported fields
}

Function represents a function that may have a delayed invocation.

func Func

func Func(i interface{}) *Function

Func declares a new Function. The argument must be a function with context.Context as its first argument.

This function must be called at program initialization time. That means it must be called in a global variable declaration or from an init function. This restriction is necessary because the instance that delays a function call may not be the one that executes it. Only the code executed at program initialization time is guaranteed to have been run by an instance before it receives a request.

func (*Function) Call

func (f *Function) Call(ctx context.Context, req *http.Request, queueName string, args ...interface{}) error

Call invokes a delayed function immediately.

func (*Function) Delay

func (f *Function) Delay(ctx context.Context, req *http.Request, queueName string, delay time.Duration, args ...interface{}) error

Call invokes a delayed function after a delay.

type Meta

type Meta struct {
	// The name of the queue.
	QueueName string `json:"queueName,omitempty"`

	// The "short" name of the task; a unique system-generated id.
	TaskName string `json:"taskName,omitempty"`

	// The number of times this task has been retried. For the first attempt,
	// this value is 0. This number includes attempts where the task failed due
	// to 5XX error codes and never reached the execution phase.
	TaskRetryCount int64 `json:"taskRetryCount,omitempty"`

	// The total number of times that the task has received a response from the
	// handler. Since Cloud Tasks deletes the task once a successful response
	// has been received, all previous handler responses were failures. This
	// number does not include failures due to 5XX error codes.
	TaskExecutionCount int64 `json:"taskExecutionCount,omitempty"`

	// The schedule time of the task.
	TaskETA *time.Time `json:"taskETA,omitempty"`

	// The HTTP response code from the previous retry.
	TaskPreviousResponse int `json:"taskPreviousResponse,omitempty"`

	// The reason for retrying the task.
	TaskRetryReason string `json:"taskRetryReason,omitempty"`
}

Meta contains the special HTTP request headers available to push task HTTP request handlers. These headers are set internally by Cloud Tasks.

See https://cloud.google.com/appengine/docs/standard/go/taskqueue/push/creating-handlers#reading_request_headers for a description of the fields. https://cloud.google.com/tasks/docs/creating-http-target-tasks#handler

func MetaFromContext

func MetaFromContext(ctx context.Context) Meta

Request returns the special task-queue HTTP request headers for the current task queue handler. Returns an error if called from outside a delay.Func.