tchooks

package
v46.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2022 License: MPL-2.0 Imports: 5 Imported by: 0

Documentation

Overview

This package was generated from the schema defined at /references/hooks/v1/api.json The hooks service provides a mechanism for creating tasks in response to events.

See:

How to use this package

First create a Hooks object: 

hooks := tchooks.New(nil)

and then call one or more of hooks's methods, e.g.: 

err := hooks.Ping(.....)

handling any errors... 

if err != nil {
	// handle error...
}

Taskcluster Schema

The source code of this go package was auto-generated from the API definition at <rootUrl>/references/hooks/v1/api.json together with the input and output schemas it references,

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Binding 

type Binding struct {

	// Min length: 1
	Exchange string `json:"exchange"`

	// Min length: 1
	RoutingKeyPattern string `json:"routingKeyPattern"`
}

Exchange and RoutingKeyPattern for each binding

type FailedFire 

type FailedFire struct {

	// The error that occurred when firing the task.  This is typically,
	// but not always, an API error message.
	//
	// Additional properties allowed
	Error json.RawMessage `json:"error"`

	// Possible values:
	//   * "error"
	Result string `json:"result"`

	// The time the task was created.  This will not necessarily match `task.created`.
	Time tcclient.Time `json:"time"`
}

Information about an unsuccessful firing of the hook

type HookCreationRequest 

type HookCreationRequest struct {
	Bindings []Binding `json:"bindings,omitempty"`

	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 1000
	HookGroupID string `json:"hookGroupId,omitempty"`

	// Syntax:     ^([a-zA-Z0-9-_/]*)$
	// Min length: 1
	// Max length: 1000
	HookID string `json:"hookId,omitempty"`

	Metadata HookMetadata `json:"metadata"`

	// Definition of the times at which a hook will result in creation of a task.
	// If several patterns are specified, tasks will be created at any time
	// specified by one or more patterns.
	//
	// Default:    []
	//
	// Array items:
	// Cron-like specification for when tasks should be created.  The pattern is
	// parsed in a UTC context.
	// See [cron-parser on npm](https://www.npmjs.com/package/cron-parser).
	// Note that tasks may not be created at exactly the time specified.
	Schedule []string `json:"schedule,omitempty"`

	// Template for the task definition.  This is rendered using [JSON-e](https://json-e.js.org/)
	// as described in [firing hooks](/docs/reference/core/hooks/firing-hooks) to produce
	// a task definition that is submitted to the Queue service.
	//
	// Additional properties allowed
	Task json.RawMessage `json:"task"`

	// Default:    {
	//               "additionalProperties": false,
	//               "type": "object"
	//             }
	//
	// Additional properties allowed
	TriggerSchema json.RawMessage `json:"triggerSchema,omitempty"`
}

Definition of a hook that can create tasks at defined times.

type HookDefinition 

type HookDefinition struct {
	Bindings []Binding `json:"bindings,omitempty"`

	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 1000
	HookGroupID string `json:"hookGroupId"`

	// Syntax:     ^([a-zA-Z0-9-_/]*)$
	// Min length: 1
	// Max length: 1000
	HookID string `json:"hookId"`

	Metadata HookMetadata `json:"metadata"`

	// A list of cron-style definitions to represent a set of moments in (UTC) time.
	// If several patterns are specified, a given moment in time represented by
	// more than one pattern is considered only to be counted once, in other words
	// it is allowed for the cron patterns to overlap; duplicates are redundant.
	//
	// Array items:
	// Cron-like specification for when tasks should be created.  The pattern is
	// parsed in a UTC context.
	// See [cron-parser on npm](https://www.npmjs.com/package/cron-parser).
	Schedule []string `json:"schedule"`

	// Template for the task definition.  This is rendered using [JSON-e](https://json-e.js.org/)
	// as described in [firing hooks](/docs/reference/core/hooks/firing-hooks) to produce
	// a task definition that is submitted to the Queue service.
	//
	// Additional properties allowed
	Task json.RawMessage `json:"task"`

	// Additional properties allowed
	TriggerSchema json.RawMessage `json:"triggerSchema"`
}

Definition of a hook that will create tasks when defined events occur.

type HookGroups 

type HookGroups struct {

	// Array items:
	Groups []string `json:"groups"`
}

List of `hookGroupIds`.

type HookList 

type HookList struct {
	Hooks []HookDefinition `json:"hooks"`
}

List of hooks

type HookMetadata 

type HookMetadata struct {

	// Long-form of the hook's purpose and behavior
	//
	// Max length: 32768
	Description string `json:"description"`

	// Whether to email the owner on an error creating the task.
	//
	// Default:    true
	EmailOnError bool `json:"emailOnError,omitempty"`

	// Human readable name of the hook
	//
	// Max length: 255
	Name string `json:"name"`

	// Email of the person or group responsible for this hook.
	//
	// Max length: 255
	Owner string `json:"owner"`
}

type HookStatusResponse 

type HookStatusResponse struct {

	// Information about the last time this hook fired.  This property is only present
	// if the hook has fired at least once.
	//
	// One of:
	//   * SuccessfulFire
	//   * FailedFire
	//   * NoFire
	LastFire json.RawMessage `json:"lastFire"`

	// The next time this hook's task is scheduled to be created. This property
	// is only present if there is a scheduled next time. Some hooks don't have
	// any schedules.
	NextScheduledDate tcclient.Time `json:"nextScheduledDate,omitempty"`
}

A snapshot of the current status of a hook.

type Hooks 

type Hooks tcclient.Client

func New 

func New(credentials *tcclient.Credentials, rootURL string) *Hooks

New returns a Hooks client, configured to run against production. Pass in nil credentials to create a client without authentication. The returned client is mutable, so returned settings can be altered. 

hooks := tchooks.New(
    nil,                                      // client without authentication
    "http://localhost:1234/my/taskcluster",   // taskcluster hosted at this root URL on local machine
)
err := hooks.Ping(.....)                      // for example, call the Ping(.....) API endpoint (described further down)...
if err != nil {
	// handle errors...
}

func NewFromEnv 

func NewFromEnv() *Hooks

NewFromEnv returns a *Hooks configured from environment variables.

The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty string.

The credentials are taken from environment variables: 

TASKCLUSTER_CLIENT_ID
TASKCLUSTER_ACCESS_TOKEN
TASKCLUSTER_CERTIFICATE

If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be disabled.

func (*Hooks) CreateHook 

func (hooks *Hooks) CreateHook(hookGroupId, hookId string, payload *HookCreationRequest) (*HookDefinition, error)

This endpoint will create a new hook.

The caller's credentials must include the role that will be used to create the task. That role must satisfy task.scopes as well as the necessary scopes to add the task to the queue.

Required scopes: 

All of:
* hooks:modify-hook:<hookGroupId>/<hookId>
* assume:hook-id:<hookGroupId>/<hookId>

See #createHook

func (*Hooks) GetHookStatus 

func (hooks *Hooks) GetHookStatus(hookGroupId, hookId string) (*HookStatusResponse, error)

Stability: *** DEPRECATED ***

This endpoint will return the current status of the hook. This represents a snapshot in time and may vary from one call to the next.

This method is deprecated in favor of listLastFires.

Required scopes: 

hooks:status:<hookGroupId>/<hookId>

See #getHookStatus

func (*Hooks) GetHookStatus_SignedURL 

func (hooks *Hooks) GetHookStatus_SignedURL(hookGroupId, hookId string, duration time.Duration) (*url.URL, error)

Returns a signed URL for GetHookStatus, valid for the specified duration.

Required scopes: 

hooks:status:<hookGroupId>/<hookId>

See GetHookStatus for more details.

func (*Hooks) GetTriggerToken 

func (hooks *Hooks) GetTriggerToken(hookGroupId, hookId string) (*TriggerTokenResponse, error)

Retrieve a unique secret token for triggering the specified hook. This token can be deactivated with `resetTriggerToken`.

Required scopes: 

hooks:get-trigger-token:<hookGroupId>/<hookId>

See #getTriggerToken

func (*Hooks) GetTriggerToken_SignedURL 

func (hooks *Hooks) GetTriggerToken_SignedURL(hookGroupId, hookId string, duration time.Duration) (*url.URL, error)

Returns a signed URL for GetTriggerToken, valid for the specified duration.

Required scopes: 

hooks:get-trigger-token:<hookGroupId>/<hookId>

See GetTriggerToken for more details.

func (*Hooks) Heartbeat 

func (hooks *Hooks) Heartbeat() error

Respond with a service heartbeat.

This endpoint is used to check on backing services this service depends on.

See #heartbeat

func (*Hooks) Hook 

func (hooks *Hooks) Hook(hookGroupId, hookId string) (*HookDefinition, error)

This endpoint will return the hook definition for the given `hookGroupId` and hookId.

Required scopes: 

hooks:get:<hookGroupId>:<hookId>

See #hook

func (*Hooks) Hook_SignedURL 

func (hooks *Hooks) Hook_SignedURL(hookGroupId, hookId string, duration time.Duration) (*url.URL, error)

Returns a signed URL for Hook, valid for the specified duration.

Required scopes: 

hooks:get:<hookGroupId>:<hookId>

See Hook for more details.

func (*Hooks) Lbheartbeat 

func (hooks *Hooks) Lbheartbeat() error

Respond without doing anything. This endpoint is used to check that the service is up.

See #lbheartbeat

func (*Hooks) ListHookGroups 

func (hooks *Hooks) ListHookGroups() (*HookGroups, error)

This endpoint will return a list of all hook groups with at least one hook.

Required scopes: 

hooks:list-hooks:

See #listHookGroups

func (*Hooks) ListHookGroups_SignedURL 

func (hooks *Hooks) ListHookGroups_SignedURL(duration time.Duration) (*url.URL, error)

Returns a signed URL for ListHookGroups, valid for the specified duration.

Required scopes: 

hooks:list-hooks:

See ListHookGroups for more details.

func (*Hooks) ListHooks 

func (hooks *Hooks) ListHooks(hookGroupId string) (*HookList, error)

This endpoint will return a list of all the hook definitions within a given hook group.

Required scopes: 

hooks:list-hooks:<hookGroupId>

See #listHooks

func (*Hooks) ListHooks_SignedURL 

func (hooks *Hooks) ListHooks_SignedURL(hookGroupId string, duration time.Duration) (*url.URL, error)

Returns a signed URL for ListHooks, valid for the specified duration.

Required scopes: 

hooks:list-hooks:<hookGroupId>

See ListHooks for more details.

func (*Hooks) ListLastFires 

func (hooks *Hooks) ListLastFires(hookGroupId, hookId, continuationToken, limit string) (*LastFiresList, error)

This endpoint will return information about the the last few times this hook has been fired, including whether the hook was fired successfully or not

By default this endpoint will return up to 1000 most recent fires in one request.

Required scopes: 

hooks:list-last-fires:<hookGroupId>/<hookId>

See #listLastFires

func (*Hooks) ListLastFires_SignedURL 

func (hooks *Hooks) ListLastFires_SignedURL(hookGroupId, hookId, continuationToken, limit string, duration time.Duration) (*url.URL, error)

Returns a signed URL for ListLastFires, valid for the specified duration.

Required scopes: 

hooks:list-last-fires:<hookGroupId>/<hookId>

See ListLastFires for more details.

func (*Hooks) Ping 

func (hooks *Hooks) Ping() error

Respond without doing anything. This endpoint is used to check that the service is up.

See #ping

func (*Hooks) RemoveHook 

func (hooks *Hooks) RemoveHook(hookGroupId, hookId string) error

This endpoint will remove a hook definition.

Required scopes: 

hooks:modify-hook:<hookGroupId>/<hookId>

See #removeHook

func (*Hooks) ResetTriggerToken 

func (hooks *Hooks) ResetTriggerToken(hookGroupId, hookId string) (*TriggerTokenResponse, error)

Reset the token for triggering a given hook. This invalidates token that may have been issued via getTriggerToken with a new token.

Required scopes: 

hooks:reset-trigger-token:<hookGroupId>/<hookId>

See #resetTriggerToken

func (*Hooks) TriggerHook 

func (hooks *Hooks) TriggerHook(hookGroupId, hookId string, payload *TriggerHookRequest) (*TriggerHookResponse, error)

This endpoint will trigger the creation of a task from a hook definition.

The HTTP payload must match the hooks `triggerSchema`. If it does, it is provided as the `payload` property of the JSON-e context used to render the task template.

Required scopes: 

hooks:trigger-hook:<hookGroupId>/<hookId>

See #triggerHook

func (*Hooks) TriggerHookWithToken 

func (hooks *Hooks) TriggerHookWithToken(hookGroupId, hookId, token string, payload *TriggerHookRequest) (*TriggerHookResponse, error)

This endpoint triggers a defined hook with a valid token.

The HTTP payload must match the hooks `triggerSchema`. If it does, it is provided as the `payload` property of the JSON-e context used to render the task template.

See #triggerHookWithToken

func (*Hooks) UpdateHook 

func (hooks *Hooks) UpdateHook(hookGroupId, hookId string, payload *HookCreationRequest) (*HookDefinition, error)

This endpoint will update an existing hook. All fields except `hookGroupId` and `hookId` can be modified.

Required scopes: 

All of:
* hooks:modify-hook:<hookGroupId>/<hookId>
* assume:hook-id:<hookGroupId>/<hookId>

See #updateHook

func (*Hooks) Version 

func (hooks *Hooks) Version() error

Respond with the JSON version object. https://github.com/mozilla-services/Dockerflow/blob/main/docs/version_object.md

See #version

type LastFiresList 

type LastFiresList struct {

	// A continuation token is returned if there are more results than listed
	// here. You can optionally provide the token in the request payload to
	// load the additional results.
	ContinuationToken string `json:"continuationToken,omitempty"`

	LastFires []Var `json:"lastFires"`
}

List of lastFires

type NoFire 

type NoFire struct {

	// Possible values:
	//   * "no-fire"
	Result string `json:"result"`
}

Information about no firing of the hook (e.g., a new hook)

type Status 

type Status struct {

	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	TaskID string `json:"taskId,omitempty"`
}

Another copy of the taskId, at the location where it was published in Taskcluster versions before v42. Prefer to use the top-level property, as `status.taskId` may be removed in future versions.

type SuccessfulFire 

type SuccessfulFire struct {

	// Possible values:
	//   * "success"
	Result string `json:"result"`

	// The task created
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	TaskID string `json:"taskId"`

	// The time the task was created.  This will not necessarily match `task.created`.
	Time tcclient.Time `json:"time"`
}

Information about a successful firing of the hook

type TriggerHookRequest 

type TriggerHookRequest json.RawMessage

A request to trigger a hook. The payload must be a JSON object, and is used as the context for a JSON-e rendering of the hook's task template, as described in "Firing Hooks".

Additional properties allowed

func (*TriggerHookRequest) MarshalJSON 

func (this *TriggerHookRequest) MarshalJSON() ([]byte, error)

MarshalJSON calls json.RawMessage method of the same name. Required since TriggerHookRequest is of type json.RawMessage...

func (*TriggerHookRequest) UnmarshalJSON 

func (this *TriggerHookRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON is a copy of the json.RawMessage implementation.

type TriggerHookResponse 

type TriggerHookResponse json.RawMessage

Response to a `triggerHook` or `triggerHookWithToken` call.

In most cases, this gives a `taskId`, but in cases where the hook template does not generate a task, it is an empty object with no `taskId`.

Any of:

  • TriggerHookResponse1
  • TriggerHookResponse2

func (*TriggerHookResponse) MarshalJSON 

func (this *TriggerHookResponse) MarshalJSON() ([]byte, error)

MarshalJSON calls json.RawMessage method of the same name. Required since TriggerHookResponse is of type json.RawMessage...

func (*TriggerHookResponse) UnmarshalJSON 

func (this *TriggerHookResponse) UnmarshalJSON(data []byte) error

UnmarshalJSON is a copy of the json.RawMessage implementation.

type TriggerHookResponse1 

type TriggerHookResponse1 struct {

	// Another copy of the taskId, at the location where it was published in
	// Taskcluster versions before v42.  Prefer to use the top-level property,
	// as `status.taskId` may be removed in future versions.
	Status Status `json:"status,omitempty"`

	// TaskId of the task created by triggering the hook.
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	TaskID string `json:"taskId"`
}

Response identifying the created task

type TriggerHookResponse2 

type TriggerHookResponse2 struct {
}

Empty response indicating no task was created

type TriggerTokenResponse 

type TriggerTokenResponse struct {
	Token string `json:"token"`
}

Secret token for a trigger

type Var 

type Var struct {

	// The error that occurred when firing the task. This is typically,
	// but not always, an API error message.
	Error string `json:"error"`

	// Possible values:
	//   * "schedule"
	//   * "triggerHook"
	//   * "triggerHookWithToken"
	//   * "pulseMessage"
	FiredBy string `json:"firedBy"`

	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 1000
	HookGroupID string `json:"hookGroupId"`

	// Syntax:     ^([a-zA-Z0-9-_/]*)$
	// Min length: 1
	// Max length: 1000
	HookID string `json:"hookId"`

	// Information about success or failure of firing of the hook
	//
	// Possible values:
	//   * "success"
	//   * "error"
	Result string `json:"result"`

	// Time when the task was created
	TaskCreateTime tcclient.Time `json:"taskCreateTime"`

	// Unique task identifier, this is UUID encoded as
	// [URL-safe base64](http://tools.ietf.org/html/rfc4648#section-5) and
	// stripped of `=` padding.
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	TaskID string `json:"taskId"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.