tcclient

package module

v24.1.7 Latest Latest Go to latest Published: Jan 4, 2020 License: MPL-2.0 Imports: 22 Imported by: 12

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/taskcluster/taskcluster

Links

Open Source Insights

README ¶

Taskcluster Client Go

A go (golang) port of taskcluster-client.

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, some example programs are included that use both the HTTP APIs and the AMQP APIs:

This HTTP example program demonstrates the use of the tcauth package to query the expiry and expanded scopes of a given clientId.
This HTTP example program demonstrates the use of the tcauth package to update an existing clientId with a new description and expiry.
The AMQP example program demonstrates the use of the tcqueueevents package to listen in on Taskcluster tasks being defined and executed.

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/clients/client-go/v24"
	"github.com/taskcluster/taskcluster/clients/client-go/v24/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: "some-provisioner-id",
		Requires:      "all-completed",
		Retries:       5,
		Routes:        []string{},
		SchedulerID:   "-",
		Scopes:        []string{},
		Tags:          map[string]string{},
		TaskGroupID:   taskID,
		WorkerType:    "some-worker-type",
	}

	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/docs/manual/design/apis/hawk/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/clients/client-go/v24"
	"github.com/taskcluster/taskcluster/clients/client-go/v24/tcqueue"
)

const (
	taskID  = "VESwp9JaRo-XkFN_bemBhw"
	runID   = 0
    rootURL = "https://tc.example.com"
)

// 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/clients/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/clients/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, rootURL)
	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.

Generating

The libraries provided by this client are auto-generated based on the schema references in this repository. This is done with the yarn generate command, run from the top level of the repository.

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

Documentation ¶

Index ¶

func RootURLFromEnvVars() string
type APICall
type APICallException
- func (err *APICallException) Error() string
type CallSummary
- func (cs *CallSummary) String() string
type Certificate
- func (cert *Certificate) Sign(accessToken string, tempClientID string) (err error)
type Client
type Credentials
- func CredentialsFromEnvVars() *Credentials
type ExtHeader
type ReducedHTTPClient
type Time

Examples ¶

Credentials.CreateTemporaryCredentials

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

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 Root URL of the Taskcluster deployment
	RootURL string
	// The (short) name of the service being accessed
	ServiceName string
	// The API version of the service being accessed
	APIVersion 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 RootURL 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/clients/client-go/v24"
)

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.

Source Files ¶

View all Source files

Directories ¶

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

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.
integrationtest 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
readwriteseeker
tcauth Authentication related API end-points for Taskcluster and related services.	Authentication related API end-points for Taskcluster and related services.
tcauthevents 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.
tcawsprovisionerevents Exchanges from the provisioner...	Exchanges from the provisioner...
tcgithub 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.
tcgithubevents 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.
tchooks 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.
tchooksevents The hooks service is responsible for creating tasks at specific times orin .	The hooks service is responsible for creating tasks at specific times orin .
tcindex The index service is responsible for indexing tasks.	The index service is responsible for indexing tasks.
tcnotify 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.
tcnotifyevents 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.
tcpurgecache The purge-cache service is responsible for tracking cache-purge requests.	The purge-cache service is responsible for tracking cache-purge requests.
tcpurgecacheevents 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.
tcqueue 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.
tcqueueevents 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.
tcsecrets 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.
tcworkermanager This service manages workers, including provisioning for dynamic worker pools.	This service manages workers, including provisioning for dynamic worker pools.
tcworkermanagerevents 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.