// Stability: *** EXPERIMENTAL ***
//
// Returns a list of artifacts and associated meta-data for the latest run
// from the given task.
//
// As a task may have many artifacts paging may be necessary. If this
// end-point returns a `continuationToken`, you should call the end-point
// again with the `continuationToken` as the query-string option:
// `continuationToken`.
//
// By default this end-point will list up-to 1000 artifacts in a single page
// you may limit this with the query-string parameter `limit`.
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#listLatestArtifacts
func (myQueue *Queue) ListLatestArtifacts(taskId, continuationToken, limit string) (*ListArtifactsResponse, error) {
v := url.Values{}
v.Add("continuationToken", continuationToken)
v.Add("limit", limit)
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(nil, "GET", "/task/"+url.QueryEscape(taskId)+"/artifacts", new(ListArtifactsResponse), v)
return responseObject.(*ListArtifactsResponse), err
}
// Returns a signed URL for GetLatestArtifact, valid for the specified duration.
//
// Required scopes:
// * queue:get-artifact:<name>
//
// See GetLatestArtifact for more details.
func (myQueue *Queue) GetLatestArtifact_SignedURL(taskId, name string, duration time.Duration) (*url.URL, error) {
cd := tcclient.ConnectionData(*myQueue)
return (&cd).SignedURL("/task/"+url.QueryEscape(taskId)+"/artifacts/"+url.QueryEscape(name), nil, duration)
}
// Get artifact by `<name>` from the last run of a task.
//
// **Public Artifacts**, in-order to get an artifact you need the scope
// `queue:get-artifact:<name>`, where `<name>` is the name of the artifact.
// But if the artifact `name` starts with `public/`, authentication and
// authorization is not necessary to fetch the artifact.
//
// **API Clients**, this method will redirect you to the artifact, if it is
// stored externally. Either way, the response may not be JSON. So API
// client users might want to generate a signed URL for this end-point and
// use that URL with a normal HTTP client.
//
// **Remark**, this end-point is slightly slower than
// `queue.getArtifact`, so consider that if you already know the `runId` of
// the latest run. Otherwise, just us the most convenient API end-point.
//
// Required scopes:
// * queue:get-artifact:<name>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#getLatestArtifact
func (myQueue *Queue) GetLatestArtifact(taskId, name string) error {
cd := tcclient.ConnectionData(*myQueue)
_, _, err := (&cd).APICall(nil, "GET", "/task/"+url.QueryEscape(taskId)+"/artifacts/"+url.QueryEscape(name), nil, nil)
return err
}
// This API end-point creates an artifact for a specific run of a task. This
// should **only** be used by a worker currently operating on this task, or
// from a process running within the task (ie. on the worker).
//
// All artifacts must specify when they `expires`, the queue will
// automatically take care of deleting artifacts past their
// expiration point. This features makes it feasible to upload large
// intermediate artifacts from data processing applications, as the
// artifacts can be set to expire a few days later.
//
// We currently support 4 different `storageType`s, each storage type have
// slightly different features and in some cases difference semantics.
//
// **S3 artifacts**, is useful for static files which will be stored on S3.
// When creating an S3 artifact the queue will return a pre-signed URL
// to which you can do a `PUT` request to upload your artifact. Note
// that `PUT` request **must** specify the `content-length` header and
// **must** give the `content-type` header the same value as in the request
// to `createArtifact`.
//
// **Azure artifacts**, are stored in _Azure Blob Storage_ service, which
// given the consistency guarantees and API interface offered by Azure is
// more suitable for artifacts that will be modified during the execution
// of the task. For example docker-worker has a feature that persists the
// task log to Azure Blob Storage every few seconds creating a somewhat
// live log. A request to create an Azure artifact will return a URL
// featuring a [Shared-Access-Signature](http://msdn.microsoft.com/en-us/library/azure/dn140256.aspx),
// refer to MSDN for further information on how to use these.
// **Warning: azure artifact is currently an experimental feature subject
// to changes and data-drops.**
//
// **Reference artifacts**, only consists of meta-data which the queue will
// store for you. These artifacts really only have a `url` property and
// when the artifact is requested the client will be redirect the URL
// provided with a `303` (See Other) redirect. Please note that we cannot
// delete artifacts you upload to other service, we can only delete the
// reference to the artifact, when it expires.
//
// **Error artifacts**, only consists of meta-data which the queue will
// store for you. These artifacts are only meant to indicate that you the
// worker or the task failed to generate a specific artifact, that you
// would otherwise have uploaded. For example docker-worker will upload an
// error artifact, if the file it was supposed to upload doesn't exists or
// turns out to be a directory. Clients requesting an error artifact will
// get a `403` (Forbidden) response. This is mainly designed to ensure that
// dependent tasks can distinguish between artifacts that were suppose to
// be generated and artifacts for which the name is misspelled.
//
// **Artifact immutability**, generally speaking you cannot overwrite an
// artifact when created. But if you repeat the request with the same
// properties the request will succeed as the operation is idempotent.
// This is useful if you need to refresh a signed URL while uploading.
// Do not abuse this to overwrite artifacts created by another entity!
// Such as worker-host overwriting artifact created by worker-code.
//
// As a special case the `url` property on _reference artifacts_ can be
// updated. You should only use this to update the `url` property for
// reference artifacts your process has created.
//
// Required scopes:
// * (queue:create-artifact:<name> and assume:worker-id:<workerGroup>/<workerId>), or
// * queue:create-artifact:<taskId>/<runId>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#createArtifact
func (myQueue *Queue) CreateArtifact(taskId, runId, name string, payload *PostArtifactRequest) (*PostArtifactResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(payload, "POST", "/task/"+url.QueryEscape(taskId)+"/runs/"+url.QueryEscape(runId)+"/artifacts/"+url.QueryEscape(name), new(PostArtifactResponse), nil)
return responseObject.(*PostArtifactResponse), err
}
// Resolve a run as _exception_. Generally, you will want to report tasks as
// failed instead of exception. You should `reportException` if,
//
// * The `task.payload` is invalid,
// * Non-existent resources are referenced,
// * Declared actions cannot be executed due to unavailable resources,
// * The worker had to shutdown prematurely,
// * The worker experienced an unknown error, or,
// * The task explicitely requested a retry.
//
// Do not use this to signal that some user-specified code crashed for any
// reason specific to this code. If user-specific code hits a resource that
// is temporarily unavailable worker should report task _failed_.
//
// Required scopes:
// * (queue:resolve-task and assume:worker-id:<workerGroup>/<workerId>), or
// * queue:resolve-task:<taskId>/<runId>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#reportException
func (myQueue *Queue) ReportException(taskId, runId string, payload *TaskExceptionRequest) (*TaskStatusResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(payload, "POST", "/task/"+url.QueryEscape(taskId)+"/runs/"+url.QueryEscape(runId)+"/exception", new(TaskStatusResponse), nil)
return responseObject.(*TaskStatusResponse), err
}
// Report a run failed, resolving the run as `failed`. Use this to resolve
// a run that failed because the task specific code behaved unexpectedly.
// For example the task exited non-zero, or didn't produce expected output.
//
// Do not use this if the task couldn't be run because if malformed
// payload, or other unexpected condition. In these cases we have a task
// exception, which should be reported with `reportException`.
//
// Required scopes:
// * (queue:resolve-task and assume:worker-id:<workerGroup>/<workerId>), or
// * queue:resolve-task:<taskId>/<runId>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#reportFailed
func (myQueue *Queue) ReportFailed(taskId, runId string) (*TaskStatusResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(nil, "POST", "/task/"+url.QueryEscape(taskId)+"/runs/"+url.QueryEscape(runId)+"/failed", new(TaskStatusResponse), nil)
return responseObject.(*TaskStatusResponse), err
}
// Returns a signed URL for Get, valid for the specified duration.
//
// Required scopes:
// * secrets:get:<name>
//
// See Get for more details.
func (mySecrets *Secrets) Get_SignedURL(name string, duration time.Duration) (*url.URL, error) {
cd := tcclient.ConnectionData(*mySecrets)
return (&cd).SignedURL("/secret/"+url.QueryEscape(name), nil, duration)
}
// Stability: *** EXPERIMENTAL ***
//
// Documented later...
//
// **Warning** this api end-point is **not stable**.
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#ping
func (myQueue *Queue) Ping() error {
cd := tcclient.ConnectionData(*myQueue)
_, _, err := (&cd).APICall(nil, "GET", "/ping", nil, nil)
return err
}
// Returns a signed URL for PollTaskUrls, valid for the specified duration.
//
// Required scopes:
// * (queue:poll-task-urls and assume:worker-type:<provisionerId>/<workerType>), or
// * queue:poll-task-urls:<provisionerId>/<workerType>
//
// See PollTaskUrls for more details.
func (myQueue *Queue) PollTaskUrls_SignedURL(provisionerId, workerType string, duration time.Duration) (*url.URL, error) {
cd := tcclient.ConnectionData(*myQueue)
return (&cd).SignedURL("/poll-task-url/"+url.QueryEscape(provisionerId)+"/"+url.QueryEscape(workerType), nil, duration)
}
// Get a signed URLs to get and delete messages from azure queue.
// Once messages are polled from here, you can claim the referenced task
// with `claimTask`, and afterwards you should always delete the message.
//
// Required scopes:
// * (queue:poll-task-urls and assume:worker-type:<provisionerId>/<workerType>), or
// * queue:poll-task-urls:<provisionerId>/<workerType>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#pollTaskUrls
func (myQueue *Queue) PollTaskUrls(provisionerId, workerType string) (*PollTaskUrlsResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(nil, "GET", "/poll-task-url/"+url.QueryEscape(provisionerId)+"/"+url.QueryEscape(workerType), new(PollTaskUrlsResponse), nil)
return responseObject.(*PollTaskUrlsResponse), err
}
// Stability: *** DEPRECATED ***
//
// Define a task without scheduling it. This API end-point allows you to
// upload a task definition without having scheduled. The task won't be
// reported as pending until it is scheduled, see the scheduleTask API
// end-point.
//
// The purpose of this API end-point is allow schedulers to upload task
// definitions without the tasks becoming _pending_ immediately. This useful
// if you have a set of dependent tasks. Then you can upload all the tasks
// and when the dependencies of a tasks have been resolved, you can schedule
// the task by calling `/task/:taskId/schedule`. This eliminates the need to
// store tasks somewhere else while waiting for dependencies to resolve.
//
// **Important** Any scopes the task requires are also required for defining
// the task. Please see the Request Payload (Task Definition) for details.
//
// **Note** this operation is **idempotent**, as long as you upload the same
// task definition as previously defined this operation is safe to retry.
//
// Required scopes:
// * queue:define-task:<provisionerId>/<workerType>, or
// * queue:create-task:<provisionerId>/<workerType>, or
// * (queue:define-task:<provisionerId>/<workerType> and queue:task-group-id:<schedulerId>/<taskGroupId>)
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#defineTask
func (myQueue *Queue) DefineTask(taskId string, payload *TaskDefinitionRequest) (*TaskStatusResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(payload, "POST", "/task/"+url.QueryEscape(taskId)+"/define", new(TaskStatusResponse), nil)
return responseObject.(*TaskStatusResponse), err
}
// Delete the secret associated with some key.
//
// Required scopes:
// * secrets:set:<name>
//
// See https://docs.taskcluster.net/reference/core/secrets/api-docs#remove
func (mySecrets *Secrets) Remove(name string) error {
cd := tcclient.ConnectionData(*mySecrets)
_, _, err := (&cd).APICall(nil, "DELETE", "/secret/"+url.QueryEscape(name), nil, nil)
return err
}
// Set the secret associated with some key. If the secret already exists, it is
// updated instead.
//
// Required scopes:
// * secrets:set:<name>
//
// See https://docs.taskcluster.net/reference/core/secrets/api-docs#set
func (mySecrets *Secrets) Set(name string, payload *Secret) error {
cd := tcclient.ConnectionData(*mySecrets)
_, _, err := (&cd).APICall(payload, "PUT", "/secret/"+url.QueryEscape(name), nil, nil)
return err
}
// List the names of all secrets that you would have access to read. In
// other words, secret name `<X>` will only be returned if a) a secret
// with name `<X>` exists, and b) you posses the scope `secrets:get:<X>`.
//
// See https://docs.taskcluster.net/reference/core/secrets/api-docs#list
func (mySecrets *Secrets) List() (*SecretsList, error) {
cd := tcclient.ConnectionData(*mySecrets)
responseObject, _, err := (&cd).APICall(nil, "GET", "/secrets", new(SecretsList), nil)
return responseObject.(*SecretsList), err
}
// Claim any task, more to be added later... long polling up to 20s.
//
// Required scopes:
// * queue:claim-work:<provisionerId>/<workerType>, and
// * queue:worker-id:<workerGroup>/<workerId>
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#claimWork
func (myQueue *Queue) ClaimWork(provisionerId, workerType string, payload *ClaimWorkRequest) (*ClaimWorkResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(payload, "POST", "/claim-work/"+url.QueryEscape(provisionerId)+"/"+url.QueryEscape(workerType), new(ClaimWorkResponse), nil)
return responseObject.(*ClaimWorkResponse), err
}
// Get an approximate number of pending tasks for the given `provisionerId`
// and `workerType`.
//
// The underlying Azure Storage Queues only promises to give us an estimate.
// Furthermore, we cache the result in memory for 20 seconds. So consumers
// should be no means expect this to be an accurate number.
// It is, however, a solid estimate of the number of pending tasks.
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#pendingTasks
func (myQueue *Queue) PendingTasks(provisionerId, workerType string) (*CountPendingTasksResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(nil, "GET", "/pending/"+url.QueryEscape(provisionerId)+"/"+url.QueryEscape(workerType), new(CountPendingTasksResponse), nil)
return responseObject.(*CountPendingTasksResponse), err
}
// claim a task, more to be added later...
//
// Required scopes:
// * (queue:claim-task and assume:worker-type:<provisionerId>/<workerType> and assume:worker-id:<workerGroup>/<workerId>), or
// * (queue:claim-task:<provisionerId>/<workerType> and queue:worker-id:<workerGroup>/<workerId>)
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#claimTask
func (myQueue *Queue) ClaimTask(taskId, runId string, payload *TaskClaimRequest) (*TaskClaimResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(payload, "POST", "/task/"+url.QueryEscape(taskId)+"/runs/"+url.QueryEscape(runId)+"/claim", new(TaskClaimResponse), nil)
return responseObject.(*TaskClaimResponse), err
}
// Get task status structure from `taskId`
//
// See https://docs.taskcluster.net/reference/platform/queue/api-docs#status
func (myQueue *Queue) Status(taskId string) (*TaskStatusResponse, error) {
cd := tcclient.ConnectionData(*myQueue)
responseObject, _, err := (&cd).APICall(nil, "GET", "/task/"+url.QueryEscape(taskId)+"/status", new(TaskStatusResponse), nil)
return responseObject.(*TaskStatusResponse), err
}
// Read the secret associated with some key. If the secret has recently
// expired, the response code 410 is returned. If the caller lacks the
// scope necessary to get the secret, the call will fail with a 403 code
// regardless of whether the secret exists.
//
// Required scopes:
// * secrets:get:<name>
//
// See https://docs.taskcluster.net/reference/core/secrets/api-docs#get
func (mySecrets *Secrets) Get(name string) (*Secret, error) {
cd := tcclient.ConnectionData(*mySecrets)
responseObject, _, err := (&cd).APICall(nil, "GET", "/secret/"+url.QueryEscape(name), new(Secret), nil)
return responseObject.(*Secret), err
}
