tcclient

package module
v0.0.0-...-a5b7ecb Latest Latest
Warning

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

Go to latest
Published: Sep 11, 2019 License: MPL-2.0 Imports: 22 Imported by: 45

README

taskcluster-client-go

Build Status GoDoc Coverage Status License

A go (golang) port of taskcluster-client.

Deprecated

NOTE: This library has been moved into the main Taskcluster distribution.

To use the new library, change github.com/taskcluster/taskcluster-client-go to github.com/taskcluster/taskcluster/clients/client-go/v14, substituting the major version of the Taskcluster services deployment you are targeting. Omit the version (/v14) if not using Go modules.

This library will continue to be updated with changes as observed on https://taskcluster-staging.net, but that may lag or lead landed changes somewhat, and the resulting library is unversioned with respect to Taskcluster services. At some point, these updates will cease, and this repository will remain as an archive. We recommend all consumers of this library upgrade to the newer path as soon as possible.

Documentation

Complete godoc documentation here.

This library provides the following packages to interface with Taskcluster:

HTTP APIs
AMQP APIs

Example programs

To get you started quickly, I have also included some example programs that use both the http services and the amqp services:

Calling API End-Points

To invoke an API end-point, instantiate one of the HTTP API classes (from section HTTP APIs). In the following example we instantiate an instance of the Queue client class and use it to create a task.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"time"

	"github.com/taskcluster/slugid-go/slugid"
	tcclient "github.com/taskcluster/taskcluster-client-go"
	"github.com/taskcluster/taskcluster-client-go/tcqueue"
)

// *********************************************************
// These type definitions are copied from:
// https://github.com/taskcluster/generic-worker/blob/5cb2876624ce43974b1e1f96205535b037d63953/generated_windows.go#L11-L377
// *********************************************************
type (
	Artifact struct {

		// Explicitly set the value of the HTTP `Content-Type` response header when the artifact(s)
		// is/are served over HTTP(S). If not provided (this property is optional) the worker will
		// guess the content type of artifacts based on the filename extension of the file storing
		// the artifact content. It does this by looking at the system filename-to-mimetype mappings
		// defined in the Windows registry. Note, setting `contentType` on a directory artifact will
		// apply the same contentType to all files contained in the directory.
		//
		// See [mime.TypeByExtension](https://godoc.org/mime#TypeByExtension).
		//
		// Since: generic-worker 10.4.0
		ContentType string `json:"contentType,omitempty"`

		// Date when artifact should expire must be in the future, no earlier than task deadline, but
		// no later than task expiry. If not set, defaults to task expiry.
		//
		// Since: generic-worker 1.0.0
		Expires tcclient.Time `json:"expires,omitempty"`

		// Name of the artifact, as it will be published. If not set, `path` will be used.
		// Conventionally (although not enforced) path elements are forward slash separated. Example:
		// `public/build/a/house`. Note, no scopes are required to read artifacts beginning `public/`.
		// Artifact names not beginning `public/` are scope-protected (caller requires scopes to
		// download the artifact). See the Queue documentation for more information.
		//
		// Since: generic-worker 8.1.0
		Name string `json:"name,omitempty"`

		// Relative path of the file/directory from the task directory. Note this is not an absolute
		// path as is typically used in docker-worker, since the absolute task directory name is not
		// known when the task is submitted. Example: `dist\regedit.exe`. It doesn't matter if
		// forward slashes or backslashes are used.
		//
		// Since: generic-worker 1.0.0
		Path string `json:"path"`

		// Artifacts can be either an individual `file` or a `directory` containing
		// potentially multiple files with recursively included subdirectories.
		//
		// Since: generic-worker 1.0.0
		//
		// Possible values:
		//   * "file"
		//   * "directory"
		Type string `json:"type"`
	}

	// Requires scope `queue:get-artifact:<artifact-name>`.
	//
	// Since: generic-worker 5.4.0
	ArtifactContent struct {

		// Max length: 1024
		Artifact string `json:"artifact"`

		// The required SHA 256 of the content body.
		//
		// Since: generic-worker 10.8.0
		//
		// Syntax:     ^[a-f0-9]{64}$
		Sha256 string `json:"sha256,omitempty"`

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

	// Base64 encoded content of file/archive, up to 64KB (encoded) in size.
	//
	// Since: generic-worker 11.1.0
	Base64Content struct {

		// Base64 encoded content of file/archive, up to 64KB (encoded) in size.
		//
		// Since: generic-worker 11.1.0
		//
		// Syntax:     ^[A-Za-z0-9/+]+[=]{0,2}$
		// Max length: 65536
		Base64 string `json:"base64"`
	}

	// By default tasks will be resolved with `state/reasonResolved`: `completed/completed`
	// if all task commands have a zero exit code, or `failed/failed` if any command has a
	// non-zero exit code. This payload property allows customsation of the task resolution
	// based on exit code of task commands.
	ExitCodeHandling struct {

		// Exit codes for any command in the task payload to cause this task to
		// be resolved as `exception/intermittent-task`. Typically the Queue
		// will then schedule a new run of the existing `taskId` (rerun) if not
		// all task runs have been exhausted.
		//
		// See [itermittent tasks](https://docs.taskcluster.net/docs/reference/platform/taskcluster-queue/docs/worker-interaction#intermittent-tasks) for more detail.
		//
		// Since: generic-worker 10.10.0
		//
		// Array items:
		// Mininum:    1
		Retry []int64 `json:"retry,omitempty"`
	}

	// Feature flags enable additional functionality.
	//
	// Since: generic-worker 5.3.0
	FeatureFlags struct {

		// An artifact named `public/chainOfTrust.json.asc` should be generated
		// which will include information for downstream tasks to build a level
		// of trust for the artifacts produced by the task and the environment
		// it ran in.
		//
		// Since: generic-worker 5.3.0
		ChainOfTrust bool `json:"chainOfTrust,omitempty"`

		// Runs commands with UAC elevation. Only set to true when UAC is
		// enabled on the worker and Administrative privileges are required by
		// task commands. When UAC is disabled on the worker, task commands will
		// already run with full user privileges, and therefore a value of true
		// will result in a malformed-payload task exception.
		//
		// A value of true does not add the task user to the `Administrators`
		// group - see the `osGroups` property for that. Typically
		// `task.payload.osGroups` should include an Administrative group, such
		// as `Administrators`, when setting to true.
		//
		// For security, `runAsAdministrator` feature cannot be used in
		// conjunction with `chainOfTrust` feature.
		//
		// Requires scope
		// `generic-worker:run-as-administrator:<provisionerId>/<workerType>`.
		//
		// Since: generic-worker 10.11.0
		RunAsAdministrator bool `json:"runAsAdministrator,omitempty"`

		// The taskcluster proxy provides an easy and safe way to make authenticated
		// taskcluster requests within the scope(s) of a particular task. See
		// [the github project](https://github.com/taskcluster/taskcluster-proxy) for more information.
		//
		// Since: generic-worker 10.6.0
		TaskclusterProxy bool `json:"taskclusterProxy,omitempty"`
	}

	FileMount struct {

		// One of:
		//   * ArtifactContent
		//   * URLContent
		//   * RawContent
		//   * Base64Content
		Content json.RawMessage `json:"content"`

		// The filesystem location to mount the file.
		//
		// Since: generic-worker 5.4.0
		File string `json:"file"`
	}

	// This schema defines the structure of the `payload` property referred to in a
	// Taskcluster Task definition.
	GenericWorkerPayload struct {

		// Artifacts to be published.
		//
		// Since: generic-worker 1.0.0
		Artifacts []Artifact `json:"artifacts,omitempty"`

		// One entry per command (consider each entry to be interpreted as a full line of
		// a Windows™ .bat file). For example:
		// ```
		// [
		//   "set",
		//   "echo hello world > hello_world.txt",
		//   "set GOPATH=C:\\Go"
		// ]
		// ```
		//
		// Since: generic-worker 0.0.1
		//
		// Array items:
		Command []string `json:"command"`

		// Env vars must be string to __string__ mappings (not number or boolean). For example:
		// ```
		// {
		//   "PATH": "C:\\Windows\\system32;C:\\Windows",
		//   "GOOS": "windows",
		//   "FOO_ENABLE": "true",
		//   "BAR_TOTAL": "3"
		// }
		// ```
		//
		// Since: generic-worker 0.0.1
		//
		// Map entries:
		Env map[string]string `json:"env,omitempty"`

		// Feature flags enable additional functionality.
		//
		// Since: generic-worker 5.3.0
		Features FeatureFlags `json:"features,omitempty"`

		// Maximum time the task container can run in seconds.
		//
		// Since: generic-worker 0.0.1
		//
		// Mininum:    1
		// Maximum:    86400
		MaxRunTime int64 `json:"maxRunTime"`

		// Directories and/or files to be mounted.
		//
		// Since: generic-worker 5.4.0
		//
		// Array items:
		// One of:
		//   * FileMount
		//   * WritableDirectoryCache
		//   * ReadOnlyDirectory
		Mounts []json.RawMessage `json:"mounts,omitempty"`

		// By default tasks will be resolved with `state/reasonResolved`: `completed/completed`
		// if all task commands have a zero exit code, or `failed/failed` if any command has a
		// non-zero exit code. This payload property allows customsation of the task resolution
		// based on exit code of task commands.
		OnExitStatus ExitCodeHandling `json:"onExitStatus,omitempty"`

		// A list of OS Groups that the task user should be a member of. Requires scope
		// `generic-worker:os-group:<provisionerId>/<workerType>/<os-group>` for each
		// group listed.
		//
		// Since: generic-worker 6.0.0
		//
		// Array items:
		OSGroups []string `json:"osGroups,omitempty"`

		// Specifies an artifact name for publishing RDP connection information.
		//
		// Since this is potentially sensitive data, care should be taken to publish
		// to a suitably locked down path, such as
		// `login-identity/<login-identity>/rdpinfo.json` which is only readable for
		// the given login identity (for example
		// `login-identity/mozilla-ldap/pmoore@mozilla.com/rdpinfo.json`). See the
		// [artifact namespace guide](https://docs.taskcluster.net/manual/design/namespaces#artifacts) for more information.
		//
		// Use of this feature requires scope
		// `generic-worker:allow-rdp:<provisionerId>/<workerType>` which must be
		// declared as a task scope.
		//
		// The RDP connection data is published during task startup so that a user
		// may interact with the running task.
		//
		// The task environment will be retained for 12 hours after the task
		// completes, to enable an interactive user to perform investigative tasks.
		// After these 12 hours, the worker will delete the task's Windows user
		// account, and then continue with other tasks.
		//
		// No guarantees are given about the resolution status of the interactive
		// task, since the task is inherently non-reproducible and no automation
		// should rely on this value.
		//
		// Since: generic-worker 10.5.0
		RdpInfo string `json:"rdpInfo,omitempty"`

		// URL of a service that can indicate tasks superseding this one; the current `taskId`
		// will be appended as a query argument `taskId`. The service should return an object with
		// a `supersedes` key containing a list of `taskId`s, including the supplied `taskId`. The
		// tasks should be ordered such that each task supersedes all tasks appearing later in the
		// list.
		//
		// See [superseding](https://docs.taskcluster.net/reference/platform/taskcluster-queue/docs/superseding) for more detail.
		//
		// Since: generic-worker 10.2.2
		SupersederURL string `json:"supersederUrl,omitempty"`
	}

	// Byte-for-byte literal inline content of file/archive, up to 64KB in size.
	//
	// Since: generic-worker 11.1.0
	RawContent struct {

		// Byte-for-byte literal inline content of file/archive, up to 64KB in size.
		//
		// Since: generic-worker 11.1.0
		//
		// Max length: 65536
		Raw string `json:"raw"`
	}

	ReadOnlyDirectory struct {

		// One of:
		//   * ArtifactContent
		//   * URLContent
		//   * RawContent
		//   * Base64Content
		Content json.RawMessage `json:"content"`

		// The filesystem location to mount the directory volume.
		//
		// Since: generic-worker 5.4.0
		Directory string `json:"directory"`

		// Archive format of content for read only directory.
		//
		// Since: generic-worker 5.4.0
		//
		// Possible values:
		//   * "rar"
		//   * "tar.bz2"
		//   * "tar.gz"
		//   * "zip"
		Format string `json:"format"`
	}

	// URL to download content from.
	//
	// Since: generic-worker 5.4.0
	URLContent struct {

		// The required SHA 256 of the content body.
		//
		// Since: generic-worker 10.8.0
		//
		// Syntax:     ^[a-f0-9]{64}$
		Sha256 string `json:"sha256,omitempty"`

		// URL to download content from.
		//
		// Since: generic-worker 5.4.0
		URL string `json:"url"`
	}

	WritableDirectoryCache struct {

		// Implies a read/write cache directory volume. A unique name for the
		// cache volume. Requires scope `generic-worker:cache:<cache-name>`.
		// Note if this cache is loaded from an artifact, you will also require
		// scope `queue:get-artifact:<artifact-name>` to use this cache.
		//
		// Since: generic-worker 5.4.0
		CacheName string `json:"cacheName"`

		// One of:
		//   * ArtifactContent
		//   * URLContent
		//   * RawContent
		//   * Base64Content
		Content json.RawMessage `json:"content,omitempty"`

		// The filesystem location to mount the directory volume.
		//
		// Since: generic-worker 5.4.0
		Directory string `json:"directory"`

		// Archive format of the preloaded content (if `content` provided).
		//
		// Since: generic-worker 5.4.0
		//
		// Possible values:
		//   * "rar"
		//   * "tar.bz2"
		//   * "tar.gz"
		//   * "zip"
		Format string `json:"format,omitempty"`
	}
)

func fatalOnError(err error) {
	if err != nil {
		log.Fatalf("Error:\n%v", err)
	}
}

func mustCompileToRawMessage(data interface{}) *json.RawMessage {
	bytes, err := json.Marshal(data)
	fatalOnError(err)
	var JSON json.RawMessage
	err = json.Unmarshal(bytes, &JSON)
	fatalOnError(err)
	return &JSON
}

func main() {
	myQueue := tcqueue.NewFromEnv()
	taskID := slugid.Nice()
	created := time.Now()

	env := map[string]string{}

	payload := GenericWorkerPayload{
		Artifacts: []Artifact{},
		Command: []string{
			`echo Hello World!`,
		},
		Env: env,
		Features: FeatureFlags{
			ChainOfTrust: false,
		},
		MaxRunTime: 60,
		Mounts:     []json.RawMessage{},
		OSGroups:   []string{},
	}

	payloadJSON := mustCompileToRawMessage(payload)

	taskDef := &tcqueue.TaskDefinitionRequest{
		Created:      tcclient.Time(created),
		Deadline:     tcclient.Time(created.Add(time.Hour * 3)),
		Dependencies: []string{},
		Expires:      tcclient.Time(created.Add(time.Hour * 24)),
		Extra:        json.RawMessage("{}"),
		Metadata: tcqueue.TaskMetadata{
			Description: "xxxx",
			Name:        "xxxx",
			Owner:       "pmoore@mozilla.com",
			Source:      "https://hg.mozilla.org/try/file/xxxx",
		},
		Payload:       *payloadJSON,
		Priority:      "normal",
		ProvisionerID: "aws-provisioner-v1",
		Requires:      "all-completed",
		Retries:       5,
		Routes:        []string{},
		SchedulerID:   "-",
		Scopes:        []string{},
		Tags:          map[string]string{},
		TaskGroupID:   taskID,
		WorkerType:    "win2012r2",
	}

	tsr, err := myQueue.CreateTask(taskID, taskDef)
	fatalOnError(err)

	respJSON, err := json.MarshalIndent(tsr, "", "  ")
	fatalOnError(err)

	fmt.Println(string(respJSON))
	fmt.Println("")
	fmt.Printf("curl -L https://queue.taskcluster.net/v1/task/%v/runs/0/artifacts/public/logs/live.log | gunzip\n", taskID)
}

Temporary credentials

You can generate temporary credentials from permanent credentials using the go client. This may be useful if you wish to issue credentials to a third party. See https://docs.taskcluster.net/manual/apis/temporary-credentials for more information. Both named and unnamed temporary credentials are supported, although named credentials are preferred if you are not sure which type to use.

Example
package main

import (
	"fmt"
	"log"
	"os"
	"strconv"
	"time"

	tcclient "github.com/taskcluster/taskcluster-client-go"
	"github.com/taskcluster/taskcluster-client-go/tcqueue"
)

const (
	taskID = "VESwp9JaRo-XkFN_bemBhw"
	runID  = 0
)

// This simple demo lists the artifacts in run 0 of task
// VESwp9JaRo-XkFN_bemBhw. It creates permanent credentials from environment
// variables TASKCLUSTER_CLIENT_ID and TASKCLUSTER_ACCESS_TOKEN, and then
// creates temporary credentials, valid for 24 hours, from these permanent
// credentials. It queries the Queue using the temporary credentials, and with
// limited authorized scopes.
//
// Note, the queueClient.ListArtifacts(...) call doesn't require any scopes.
// The generation of temporary credentials, and limiting via authorized scopes
// is purely illustrative. The TASKCLUSTER_CLIENT_ID must satisfy
// auth:create-client:demo-client/taskcluster-client-go, though.
func main() {
	permCreds := &tcclient.Credentials{
		ClientID:    os.Getenv("TASKCLUSTER_CLIENT_ID"),
		AccessToken: os.Getenv("TASKCLUSTER_ACCESS_TOKEN"),
	}
	tempCreds, err := permCreds.CreateNamedTemporaryCredentials(
		"demo-client/taskcluster-client-go",
		time.Hour*24,
		"assume:legacy-permacred",
	)
	if err != nil {
		log.Fatalf("Could not create temporary credentials: %v", err)
	}
	tempCreds.AuthorizedScopes = []string{
		"queue:get-artifact:private/build/*",
	}
	queueClient, err := tcqueue.New(tempCreds)
	if err != nil {
		// bug in code
		log.Fatalf("SERIOUS BUG! Could not create client from generated temporary credentials: %v", err)
	}
	listArtifactsResponse, err := queueClient.ListArtifacts(taskID, strconv.Itoa(runID), "", "")
	if err != nil {
		log.Fatalf("Could not call queue.listArtifacts endpoint: %v", err)
	}
	fmt.Printf("Task %v run %v artifacts:\n", taskID, runID)
	for _, artifact := range listArtifactsResponse.Artifacts {
		fmt.Printf("  * %v\n", artifact.Name)
	}
	fmt.Println("Done")
}

See the HTTP API godocs for more information, or browse the integration tests for further examples.

Building

The libraries provided by this client are auto-generated based on the schemas listed under http://references.taskcluster.net/manifest.json combined with the supplementary information stored in apis.json.

In order to completely regenerate all of the HTTP and AMQP libraries, please run build.sh found in the top level directory. This will completely regenerate the library. Please note you will need an active internet connection as the build process must download several json files and schemas in order to build the library.

The code which generates the library can all be found under the top level codegenerator directory.

Contributing

Contributions are welcome. Please fork, and issue a Pull Request back with an explanation of your changes.

Travis

Travis build success/failure messages are posted to irc channel #taskcluster-bots on irc.mozilla.org:6697.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func BaseURL

func BaseURL(rootURL string, service string, version string) string

func RootURLFromEnvVars

func RootURLFromEnvVars() string

RootURLFromEnvVars returns the value of environment variable TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise the value of TASKCLUSTER_ROOT_URL if set, otherwise the empty string.

Types

type APICall

type APICall struct {
	Client      *Client
	Route       string
	QueryString url.Values
	Payload     io.Reader
}

type APICallException

type APICallException struct {
	CallSummary *CallSummary
	RootCause   error
}

func (*APICallException) Error

func (err *APICallException) Error() string

type CallSummary

type CallSummary struct {
	HTTPRequest *http.Request
	// Keep a copy of request body in addition to the *http.Request, since
	// accessing the Body via the *http.Request object, you get a io.ReadCloser
	// - and after the request has been made, the body will have been read, and
	// the data lost... This way, it is still available after the api call
	// returns.
	HTTPRequestBody string
	// The Go Type which is marshaled into json and used as the http request
	// body.
	HTTPRequestObject interface{}
	HTTPResponse      *http.Response
	// Keep a copy of response body in addition to the *http.Response, since
	// accessing the Body via the *http.Response object, you get a
	// io.ReadCloser - and after the response has been read once (to unmarshal
	// json into native go types) the data is lost... This way, it is still
	// available after the api call returns.
	HTTPResponseBody string
	// Keep a record of how many http requests were attempted
	Attempts int
}

CallSummary provides information about the underlying http request and response issued for a given API call.

func (*CallSummary) String

func (cs *CallSummary) String() string

type Certificate

type Certificate struct {
	Version   int      `json:"version"`
	Scopes    []string `json:"scopes"`
	Start     int64    `json:"start"`
	Expiry    int64    `json:"expiry"`
	Seed      string   `json:"seed"`
	Signature string   `json:"signature"`
	Issuer    string   `json:"issuer,omitempty"`
}

Certificate represents the certificate used in Temporary Credentials. See https://docs.taskcluster.net/docs/manual/design/apis/hawk/temporary-credentials

func (*Certificate) Sign

func (cert *Certificate) Sign(accessToken string, tempClientID string) (err error)

type Client

type Client struct {
	Credentials *Credentials
	// The Base URL of the service, beneath the root URL of the deployment.
	// Typically tcclient.BaseURL function will create it for you.
	// For example, "https://auth.taskcluster.net/v1" for current production auth service.
	BaseURL string
	// Whether authentication is enabled (e.g. set to 'false' when using taskcluster-proxy)
	Authenticate bool
	// HTTPClient is a ReducedHTTPClient to be used for the http call instead of
	// the DefaultHTTPClient.
	HTTPClient ReducedHTTPClient
	// Context that aborts all requests with this client
	Context context.Context
}

Client is the entry point into all the functionality in this package. It contains authentication credentials, and a service endpoint, which are required for all HTTP operations.

func (*Client) APICall

func (client *Client) APICall(payload interface{}, method, route string, result interface{}, query url.Values) (interface{}, *CallSummary, error)

APICall is the generic REST API calling method which performs all REST API calls for this library. Each auto-generated REST API method simply is a wrapper around this method, calling it with specific specific arguments.

func (*Client) Request

func (client *Client) Request(rawPayload []byte, method, route string, query url.Values) (*CallSummary, error)

Request is the underlying method that makes a raw API request, without performing any json marshaling/unmarshaling of requests/responses. It is useful if you wish to handle raw payloads and/or raw http response bodies, rather than calling APICall which translates []byte to/from go types.

func (*Client) SignedURL

func (client *Client) SignedURL(route string, query url.Values, duration time.Duration) (u *url.URL, err error)

SignedURL creates a signed URL using the given Client, where route is the url path relative to the BaseURL stored in the Client, query is the set of query string parameters, if any, and duration is the amount of time that the signed URL should remain valid for.

type Credentials

type Credentials struct {
	// ClientID
	ClientID string `json:"clientId"`
	// AccessToken
	AccessToken string `json:"accessToken"`
	// Certificate used only for temporary credentials
	Certificate string `json:"certificate"`
	// AuthorizedScopes if set to nil, is ignored. Otherwise, it should be a
	// subset of the scopes that the ClientId already has, and restricts the
	// Credentials to only having these scopes. This is useful when performing
	// actions on behalf of a client which has more restricted scopes. Setting
	// to nil is not the same as setting to an empty array. If AuthorizedScopes
	// is set to an empty array rather than nil, this is equivalent to having
	// no scopes at all.
	// See https://docs.taskcluster.net/docs/manual/design/apis/hawk/authorized-scopes
	AuthorizedScopes []string `json:"authorizedScopes"`
}

Credentials represents the set of credentials required to access protected Taskcluster HTTP APIs.

func CredentialsFromEnvVars

func CredentialsFromEnvVars() *Credentials

CredentialsFromEnvVars creates and returns Taskcluster credentials initialised from the values of environment variables:

TASKCLUSTER_CLIENT_ID
TASKCLUSTER_ACCESS_TOKEN
TASKCLUSTER_CERTIFICATE

No validation is performed on the assigned values, and unset environment variables will result in empty string values.

func (*Credentials) Cert

func (creds *Credentials) Cert() (cert *Certificate, err error)

Cert attempts to parse the certificate string to return it as an object. If the certificate is an empty string (e.g. in the case of permanent credentials) then a nil pointer is returned for the certificate. If a certificate has been specified but cannot be parsed, an error is returned, and cert is an empty certificate (rather than nil).

func (*Credentials) CreateNamedTemporaryCredentials

func (permaCreds *Credentials) CreateNamedTemporaryCredentials(tempClientID string, duration time.Duration, scopes ...string) (tempCreds *Credentials, err error)

CreateNamedTemporaryCredentials generates temporary credentials from permanent credentials, valid for the given duration, starting immediately. The temporary credentials' scopes must be a subset of the permanent credentials' scopes. The duration may not be more than 31 days. Any authorized scopes of the permanent credentials will be passed through as authorized scopes to the temporary credentials, but will not be restricted via the certificate.

Note that the auth service already applies a 5 minute clock skew to the start and expiry times in https://github.com/taskcluster/taskcluster-auth/pull/117 so no clock skew is applied in this method, nor should be applied by the caller.

See https://docs.taskcluster.net/docs/manual/design/apis/hawk/temporary-credentials

func (*Credentials) CreateTemporaryCredentials

func (permaCreds *Credentials) CreateTemporaryCredentials(duration time.Duration, scopes ...string) (tempCreds *Credentials, err error)

CreateTemporaryCredentials is an alias for CreateNamedTemporaryCredentials with an empty name.

Example
package main

import (
	"fmt"
	"os"
	"time"

	tcclient "github.com/taskcluster/taskcluster-client-go"
)

func main() {
	permaCreds := tcclient.Credentials{
		ClientID:    os.Getenv("TASKCLUSTER_CLIENT_ID"),
		AccessToken: os.Getenv("TASKCLUSTER_ACCESS_TOKEN"),
	}
	tempCreds, err := permaCreds.CreateTemporaryCredentials(24*time.Hour, "dummy:scope:1", "dummy:scope:2")
	if err != nil {
		// handle error
	}
	fmt.Printf("Temporary creds:\n%q\n", tempCreds)
}
Output:

func (*Credentials) SignRequest

func (c *Credentials) SignRequest(req *http.Request) (err error)

SignRequest will add an Authorization header

func (*Credentials) String

func (creds *Credentials) String() string

type ExtHeader

type ExtHeader struct {
	Certificate *Certificate `json:"certificate,omitempty"`
	// use pointer to slice to distinguish between nil slice and empty slice
	AuthorizedScopes *[]string `json:"authorizedScopes,omitempty"`
}

ExtHeader represents the authentication/authorization data that is contained in the ext field inside the base64 decoded `Authorization` HTTP header in outgoing Hawk HTTP requests.

type ReducedHTTPClient

type ReducedHTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

ReducedHTTPClient is the interface that wraps the functionality of http.Client that we actually use in Client.APICall.

type Time

type Time time.Time

Time wraps time.Time in order that json serialisation/deserialisation can be adapted. Marshaling time.Time types results in RFC3339 dates with nanosecond precision in the user's timezone. In order that the json date representation is consistent between what we send in json payloads, and what taskcluster services return, we wrap time.Time into type tcclient.Time which marshals instead to the same format used by the Taskcluster services; UTC based, with millisecond precision, using 'Z' timezone, e.g. 2015-10-27T20:36:19.255Z.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. The time is a quoted string in RFC 3339 format, with sub-second precision added if present.

func (Time) String

func (t Time) String() string

Returns the Time in canonical RFC3339 representation, e.g. 2015-10-27T20:36:19.255Z

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface. The time is expected to be a quoted string in RFC 3339 format.

Directories

Path Synopsis
codegenerator
model
Package model contains the core logic of the code generation process.
Package model contains the core logic of the code generation process.
Package integrationtest stores all the integration tests that run against the taskcluster cluster client
Package integrationtest stores all the integration tests that run against the taskcluster cluster client
Authentication related API end-points for Taskcluster and related services.
Authentication related API end-points for Taskcluster and related services.
The auth service is responsible for storing credentials, managing assignment of scopes, and validation of request signatures from other services.
The auth service is responsible for storing credentials, managing assignment of scopes, and validation of request signatures from other services.
The AWS Provisioner is responsible for provisioning instances on EC2 for use in Taskcluster.
The AWS Provisioner is responsible for provisioning instances on EC2 for use in Taskcluster.
Exchanges from the provisioner...
Exchanges from the provisioner...
A taskcluster service which manages EC2 instances.
A taskcluster service which manages EC2 instances.
This service is responsible for making pulse messages accessible from browsers and cli.
This service is responsible for making pulse messages accessible from browsers and cli.
TODO
The github service is responsible for creating tasks in reposnse to GitHub events, and posting results to the GitHub UI.
The github service is responsible for creating tasks in reposnse to GitHub events, and posting results to the GitHub UI.
The github service publishes a pulse message for supported github events, translating Github webhook events into pulse messages.
The github service publishes a pulse message for supported github events, translating Github webhook events into pulse messages.
The hooks service provides a mechanism for creating tasks in response to events.
The hooks service provides a mechanism for creating tasks in response to events.
The hooks service is responsible for creating tasks at specific times orin .
The hooks service is responsible for creating tasks at specific times orin .
The index service is responsible for indexing tasks.
The index service is responsible for indexing tasks.
The Login service serves as the interface between external authentication systems and Taskcluster credentials.
The Login service serves as the interface between external authentication systems and Taskcluster credentials.
The notification service listens for tasks with associated notifications and handles requests to send emails and post pulse messages.
The notification service listens for tasks with associated notifications and handles requests to send emails and post pulse messages.
This pretty much only contains the simple free-form message that can be published from this service from a request by anybody with the proper scopes.
This pretty much only contains the simple free-form message that can be published from this service from a request by anybody with the proper scopes.
The purge-cache service is responsible for tracking cache-purge requests.
The purge-cache service is responsible for tracking cache-purge requests.
The purge-cache service, typically available at `purge-cache.taskcluster.net`, is responsible for publishing a pulse message for workers, so they can purge cache upon request.
The purge-cache service, typically available at `purge-cache.taskcluster.net`, is responsible for publishing a pulse message for workers, so they can purge cache upon request.
The queue service is responsible for accepting tasks and track their state as they are executed by workers.
The queue service is responsible for accepting tasks and track their state as they are executed by workers.
The queue service is responsible for accepting tasks and track their state as they are executed by workers.
The queue service is responsible for accepting tasks and track their state as they are executed by workers.
The secrets service provides a simple key/value store for small bits of secret data.
The secrets service provides a simple key/value store for small bits of secret data.
The taskcluster-treeherder service is responsible for processing task events published by Taskcluster Queue and producing job messages that are consumable by Treeherder.
The taskcluster-treeherder service is responsible for processing task events published by Taskcluster Queue and producing job messages that are consumable by Treeherder.
This service manages workers, including provisioning for dynamic worker pools.
This service manages workers, including provisioning for dynamic worker pools.
These exchanges provide notifications when a worker pool is created or updated.This is so that the provisioner running in a differentprocess at the other end can synchronize to the changes.
These exchanges provide notifications when a worker pool is created or updated.This is so that the provisioner running in a differentprocess at the other end can synchronize to the changes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL