tcindex

Documentation

Overview

The following code is AUTO-GENERATED. Please DO NOT edit. To update this generated code, run the following command: in the /codegenerator/model subdirectory of this project, making sure that `${GOPATH}/bin` is in your `PATH`:

go install && go generate

This package was generated from the schema defined at /references/index/v1/api.json The index service is responsible for indexing tasks. The service ensures that tasks can be located by user-defined names.

As described in the service documentation, tasks are typically indexed via Pulse messages, so the most common use of API methods is to read from the index.

See:

How to use this package

First create an Index object:

index := tcindex.New(nil)

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

err := index.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/index/v1/api.json together with the input and output schemas it references,

Index

• type Index
  • func New(credentials *tcclient.Credentials, rootURL string) *Index
  • func NewFromEnv() *Index
  • func (index *Index) FindArtifactFromTask(indexPath, name string) error
  • func (index *Index) FindArtifactFromTask_SignedURL(indexPath, name string, duration time.Duration) (*url.URL, error)
  • func (index *Index) FindTask(indexPath string) (*IndexedTaskResponse, error)
  • func (index *Index) InsertTask(namespace string, payload *InsertTaskRequest) (*IndexedTaskResponse, error)
  • func (index *Index) ListNamespaces(namespace, continuationToken, limit string) (*ListNamespacesResponse, error)
  • func (index *Index) ListTasks(namespace, continuationToken, limit string) (*ListTasksResponse, error)
  • func (index *Index) Ping() error
• type IndexedTaskResponse
• type InsertTaskRequest
• type ListNamespacesResponse
• type ListTasksResponse
• type Namespace
• type Task

Types

type Index

type Index tcclient.Client

func New

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

New returns an Index 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.

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

func NewFromEnv

func NewFromEnv() *Index

NewFromEnv returns an *Index 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 (*Index) FindArtifactFromTask

func (index *Index) FindArtifactFromTask(indexPath, name string) error

Find a task by index path and redirect to the artifact on the most recent run with the given `name`.

Note that multiple calls to this endpoint may return artifacts from differen tasks if a new task is inserted into the index between calls. Avoid using this method as a stable link to multiple, connected files if the index path does not contain a unique identifier. For example, the following two links may return unrelated files: * https://tc.example.com/api/index/v1/task/some-app.win64.latest.installer/artifacts/public/installer.exe` * https://tc.example.com/api/index/v1/task/some-app.win64.latest.installer/artifacts/public/debug-symbols.zip`

This problem be remedied by including the revision in the index path or by bundling both installer and debug symbols into a single artifact.

If no task exists for the given index path, this API end-point responds with 404.

Required scopes:

If private:
  queue:get-artifact:<name>

See #findArtifactFromTask

func (*Index) FindArtifactFromTask_SignedURL

func (index *Index) FindArtifactFromTask_SignedURL(indexPath, name string, duration time.Duration) (*url.URL, error)

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

Required scopes:

If private:
  queue:get-artifact:<name>

See FindArtifactFromTask for more details.

func (*Index) FindTask

func (index *Index) FindTask(indexPath string) (*IndexedTaskResponse, error)

Find a task by index path, returning the highest-rank task with that path. If no task exists for the given path, this API end-point will respond with a 404 status.

See #findTask

func (*Index) InsertTask

func (index *Index) InsertTask(namespace string, payload *InsertTaskRequest) (*IndexedTaskResponse, error)

Insert a task into the index. If the new rank is less than the existing rank at the given index path, the task is not indexed but the response is still 200 OK.

Please see the introduction above for information about indexing successfully completed tasks automatically using custom routes.

Required scopes:

index:insert-task:<namespace>

See #insertTask

func (*Index) ListNamespaces

func (index *Index) ListNamespaces(namespace, continuationToken, limit string) (*ListNamespacesResponse, error)

List the namespaces immediately under a given namespace.

This endpoint lists up to 1000 namespaces. If more namespaces are present, a `continuationToken` will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.

See #listNamespaces

func (*Index) ListTasks

func (index *Index) ListTasks(namespace, continuationToken, limit string) (*ListTasksResponse, error)

List the tasks immediately under a given namespace.

This endpoint lists up to 1000 tasks. If more tasks are present, a `continuationToken` will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.

**Remark**, this end-point is designed for humans browsing for tasks, not services, as that makes little sense.

See #listTasks

func (*Index) Ping

func (index *Index) Ping() error

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

See #ping

type IndexedTaskResponse

type IndexedTaskResponse struct {

	// Data that was reported with the task. This is an arbitrary JSON object.
	//
	// Additional properties allowed
	Data json.RawMessage `json:"data"`

	// Date at which this entry expires from the task index.
	Expires tcclient.Time `json:"expires"`

	// Namespace of the indexed task, used to find the indexed task in the index.
	//
	// Max length: 255
	Namespace string `json:"namespace"`

	// If multiple tasks are indexed with the same `namespace` the task with the
	// highest `rank` will be stored and returned in later requests. If two tasks
	// has the same `rank` the latest task will be stored.
	Rank float64 `json:"rank"`

	// 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"`
}

Representation of an indexed task.

type InsertTaskRequest

type InsertTaskRequest struct {

	// This is an arbitrary JSON object. Feel free to put whatever data you want
	// here, but do limit it, you'll get errors if you store more than 32KB.
	// So stay well, below that limit.
	//
	// Additional properties allowed
	Data json.RawMessage `json:"data"`

	// Date at which this entry expires from the task index.
	Expires tcclient.Time `json:"expires"`

	// If multiple tasks are indexed with the same `namespace` the task with the
	// highest `rank` will be stored and returned in later requests. If two tasks
	// has the same `rank` the latest task will be stored.
	Rank float64 `json:"rank"`

	// 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"`
}

Representation of the index entry to insert.

type ListNamespacesResponse

type ListNamespacesResponse 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"`

	// List of namespaces.
	Namespaces []Namespace `json:"namespaces"`
}

Response from a request to list namespaces within a given namespace.

type ListTasksResponse

type ListTasksResponse 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"`

	// List of tasks.
	Tasks []Task `json:"tasks"`
}

Representation of an indexed task.

type Namespace

type Namespace struct {

	// Date at which this entry, and by implication all entries below it,
	// expires from the task index.
	Expires tcclient.Time `json:"expires"`

	// Name of namespace within it's parent namespace.
	Name string `json:"name"`

	// Fully qualified name of the namespace, you can use this to list
	// namespaces or tasks under this namespace.
	//
	// Max length: 255
	Namespace string `json:"namespace"`
}

Representation of a namespace that contains indexed tasks.

type Task

type Task struct {

	// Data that was reported with the task. This is an arbitrary JSON
	// object.
	//
	// Additional properties allowed
	Data json.RawMessage `json:"data"`

	// Date at which this entry expires from the task index.
	Expires tcclient.Time `json:"expires"`

	// Index path of the task.
	//
	// Max length: 255
	Namespace string `json:"namespace"`

	// If multiple tasks are indexed with the same `namespace` the task
	// with the highest `rank` will be stored and returned in later
	// requests. If two tasks has the same `rank` the latest task will be
	// stored.
	Rank float64 `json:"rank"`

	// Unique task identifier for the task currently indexed at `namespace`.
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	TaskID string `json:"taskId"`
}

Representation of a task.