Documentation ¶
Index ¶
- func BaseURL(rootURL string, service string, version string) string
- func RootURLFromEnvVars() string
- type APICall
- type APICallException
- type CallSummary
- type Certificate
- type Client
- func (client *Client) APICall(payload interface{}, method, route string, result interface{}, ...) (interface{}, *CallSummary, error)
- func (client *Client) Request(rawPayload []byte, method, route string, query url.Values) (*CallSummary, error)
- func (client *Client) SignedURL(route string, query url.Values, duration time.Duration) (u *url.URL, err error)
- type Credentials
- func (creds *Credentials) Cert() (cert *Certificate, err error)
- func (permaCreds *Credentials) CreateNamedTemporaryCredentials(tempClientID string, duration time.Duration, scopes ...string) (tempCreds *Credentials, err error)
- func (permaCreds *Credentials) CreateTemporaryCredentials(duration time.Duration, scopes ...string) (tempCreds *Credentials, err error)
- func (c *Credentials) SignRequest(req *http.Request) (err error)
- func (creds *Credentials) String() string
- type ExtHeader
- type ReducedHTTPClient
- type Time
Examples ¶
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 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
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 ¶
ReducedHTTPClient is the interface that wraps the functionality of http.Client that we actually use in Client.APICall.
type 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 ¶
MarshalJSON implements the json.Marshaler interface. The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
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
|
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. |