taskcluster-client-go: github.com/taskcluster/taskcluster-client-go Index | Examples | Files | Directories

package tcclient

import "github.com/taskcluster/taskcluster-client-go"

Index

Examples

Package Files

creds.go http.go time.go

Variables

var (
    RegExpClientID    *regexp.Regexp = regexp.MustCompile(`^[A-Za-z0-9@/:.+|_-]+$`)
    RegExpAccessToken *regexp.Regexp = regexp.MustCompile(`^[a-zA-Z0-9_-]{22,66}$`)
)

type APICall Uses

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

type APICallException Uses

type APICallException struct {
    CallSummary *CallSummary
    RootCause   error
}

func (*APICallException) Error Uses

func (err *APICallException) Error() string

type CallSummary Uses

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 Uses

func (cs *CallSummary) String() string

type Certificate Uses

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/manual/apis/temporary-credentials

func (*Certificate) Sign Uses

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

func (*Certificate) Validate Uses

func (cert *Certificate) Validate() error

Validate performs a sanity check of the given certificate and returns an error if it is able to determine that the certificate is not malformed, expired, or for any other reason invalid. Note, it does not perform any network transactions against any live services, it only performs sanity checks that can be executed locally. If cert is nil, an error is returned.

type Client Uses

type Client struct {
    Credentials *Credentials
    // The URL of the API endpoint to hit.
    // For example, "https://auth.taskcluster.net/v1" for 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 Uses

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 Uses

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 Uses

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 Uses

type Credentials struct {
    // ClientID must conform to ^[A-Za-z0-9@/:.+|_-]+$
    ClientID string `json:"clientId"`
    // AccessToken must conform to ^[a-zA-Z0-9_-]{22,66}$
    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/manual/apis/authorized-scopes
    AuthorizedScopes []string `json:"authorizedScopes"`
}

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

func CredentialsFromEnvVars Uses

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 loaded values, and unset environment variables will result in empty string values.

func (*Credentials) Cert Uses

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 Uses

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.

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

func (*Credentials) CreateTemporaryCredentials Uses

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

CreateTemporaryCredentials is an alias for CreateNamedTemporaryCredentials with an empty name.

Code:

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)

func (*Credentials) SignRequest Uses

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

SignRequest will add an Authorization header

func (*Credentials) String Uses

func (creds *Credentials) String() string

func (*Credentials) Validate Uses

func (creds *Credentials) Validate() error

Validate performs local lexical validation of creds to ensure the credentials are syntactically valid and returns a non-nil error if they are not. No authentication is performed, so a call to Validate with invalid credentials that are syntactically valid will not return an error.

type ExtHeader Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (t Time) String() string

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

func (*Time) UnmarshalJSON Uses

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

PathSynopsis
authAuthentication related API end-points for Taskcluster and related services.
autheventsThe auth service, typically available at `auth.taskcluster.net` is responsible for storing credentials, managing assignment of scopes, and validation of request signatures from other services.
awsprovisionerThe AWS Provisioner is responsible for provisioning instances on EC2 for use in Taskcluster.
awsprovisionereventsExchanges from the provisioner...
codegenerator/modelPackage model contains the core logic of the code generation process.
githubThe github service, typically available at `github.taskcluster.net`, is responsible for publishing pulse messages in response to GitHub events.
githubeventsThe github service, typically available at `github.taskcluster.net`, is responsible for publishing a pulse message for supported github events.
hooksHooks are a mechanism for creating tasks in response to events.
indexThe task index, typically available at `index.taskcluster.net`, is responsible for indexing tasks.
integrationtestPackage integrationtest stores all the integration tests that run against the taskcluster cluster client
loginThe Login service serves as the interface between external authentication systems and TaskCluster credentials.
notifyThe notification service, typically available at `notify.taskcluster.net` listens for tasks with associated notifications and handles requests to send emails and post pulse messages.
pulseThe taskcluster-pulse service, typically available at `pulse.taskcluster.net` manages pulse credentials for taskcluster users.
purgecacheThe 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.
purgecacheeventsThe 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.
queueThe queue, typically available at `queue.taskcluster.net`, is responsible for accepting tasks and track their state as they are executed by workers.
queueeventsThe queue, typically available at `queue.taskcluster.net`, is responsible for accepting tasks and track their state as they are executed by workers.
secretsThe secrets service provides a simple key/value store for small bits of secret data.
treeherdereventsThe taskcluster-treeherder service is responsible for processing task events published by TaskCluster Queue and producing job messages that are consumable by Treeherder.

Package tcclient imports 22 packages (graph) and is imported by 35 packages. Updated 2017-11-21. Refresh now. Tools for package owners.