X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/8b8673b66d593742deb718ab5933fa2c2a1d8672..99ca2640c855e88c7b08c3509b21be9e160ccac8:/sdk/go/arvadosclient/arvadosclient.go diff --git a/sdk/go/arvadosclient/arvadosclient.go b/sdk/go/arvadosclient/arvadosclient.go index 99b08186a5..cc99efdcf4 100644 --- a/sdk/go/arvadosclient/arvadosclient.go +++ b/sdk/go/arvadosclient/arvadosclient.go @@ -16,9 +16,14 @@ import ( "strings" ) -// Errors +type StringMatcher func(string) bool + +var UUIDMatch StringMatcher = regexp.MustCompile(`^[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{15}$`).MatchString +var PDHMatch StringMatcher = regexp.MustCompile(`^[0-9a-f]{32}\+\d+$`).MatchString + var MissingArvadosApiHost = errors.New("Missing required environment variable ARVADOS_API_HOST") var MissingArvadosApiToken = errors.New("Missing required environment variable ARVADOS_API_TOKEN") +var ErrInvalidArgument = errors.New("Invalid argument") // Indicates an error that was returned by the API server. type APIServerError struct { @@ -73,21 +78,42 @@ type ArvadosClient struct { DiscoveryDoc Dict } -// Create a new ArvadosClient, initialized with standard Arvados environment -// variables ARVADOS_API_HOST, ARVADOS_API_TOKEN, and (optionally) -// ARVADOS_API_HOST_INSECURE. +// APIConfig struct consists of: +// APIToken string +// APIHost string +// APIHostInsecure bool +// ExternalClient bool +type APIConfig struct { + APIToken string + APIHost string + APIHostInsecure bool + ExternalClient bool +} + +// Create a new ArvadosClient, initialized with standard Arvados environment variables +// ARVADOS_API_HOST, ARVADOS_API_TOKEN, ARVADOS_API_HOST_INSECURE, ARVADOS_EXTERNAL_CLIENT. func MakeArvadosClient() (ac ArvadosClient, err error) { + var config APIConfig + config.APIToken = os.Getenv("ARVADOS_API_TOKEN") + config.APIHost = os.Getenv("ARVADOS_API_HOST") + var matchTrue = regexp.MustCompile("^(?i:1|yes|true)$") - insecure := matchTrue.MatchString(os.Getenv("ARVADOS_API_HOST_INSECURE")) - external := matchTrue.MatchString(os.Getenv("ARVADOS_EXTERNAL_CLIENT")) + config.APIHostInsecure = matchTrue.MatchString(os.Getenv("ARVADOS_API_HOST_INSECURE")) + config.ExternalClient = matchTrue.MatchString(os.Getenv("ARVADOS_EXTERNAL_CLIENT")) + + return MakeArvadosClientWithConfig(config) +} + +// Create a new ArvadosClient, using the given input parameters. +func MakeArvadosClientWithConfig(config APIConfig) (ac ArvadosClient, err error) { ac = ArvadosClient{ - ApiServer: os.Getenv("ARVADOS_API_HOST"), - ApiToken: os.Getenv("ARVADOS_API_TOKEN"), - ApiInsecure: insecure, + ApiServer: config.APIHost, + ApiToken: config.APIToken, + ApiInsecure: config.APIHostInsecure, Client: &http.Client{Transport: &http.Transport{ - TLSClientConfig: &tls.Config{InsecureSkipVerify: insecure}}}, - External: external} + TLSClientConfig: &tls.Config{InsecureSkipVerify: config.APIHostInsecure}}}, + External: config.ExternalClient} if ac.ApiServer == "" { return ac, MissingArvadosApiHost @@ -99,30 +125,21 @@ func MakeArvadosClient() (ac ArvadosClient, err error) { return ac, err } -// Low-level access to a resource. -// -// method - HTTP method, one of GET, HEAD, PUT, POST or DELETE -// resource - the arvados resource to act on -// uuid - the uuid of the specific item to access (may be empty) -// action - sub-action to take on the resource or uuid (may be empty) -// parameters - method parameters -// -// return -// reader - the body reader, or nil if there was an error -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) CallRaw(method string, resource string, uuid string, action string, parameters Dict) (reader io.ReadCloser, err error) { +// CallRaw is the same as Call() but returns a Reader that reads the +// response body, instead of taking an output object. +func (c ArvadosClient) CallRaw(method string, resourceType string, uuid string, action string, parameters Dict) (reader io.ReadCloser, err error) { var req *http.Request u := url.URL{ Scheme: "https", - Host: this.ApiServer} + Host: c.ApiServer} - if resource != API_DISCOVERY_RESOURCE { + if resourceType != API_DISCOVERY_RESOURCE { u.Path = "/arvados/v1" } - if resource != "" { - u.Path = u.Path + "/" + resource + if resourceType != "" { + u.Path = u.Path + "/" + resourceType } if uuid != "" { u.Path = u.Path + "/" + uuid @@ -135,12 +152,11 @@ func (this ArvadosClient) CallRaw(method string, resource string, uuid string, a parameters = make(Dict) } - parameters["format"] = "json" - vals := make(url.Values) for k, v := range parameters { - m, err := json.Marshal(v) - if err == nil { + if s, ok := v.(string); ok { + vals.Set(k, s) + } else if m, err := json.Marshal(v); err == nil { vals.Set(k, string(m)) } } @@ -158,14 +174,14 @@ func (this ArvadosClient) CallRaw(method string, resource string, uuid string, a } // Add api token header - req.Header.Add("Authorization", fmt.Sprintf("OAuth2 %s", this.ApiToken)) - if this.External { + req.Header.Add("Authorization", fmt.Sprintf("OAuth2 %s", c.ApiToken)) + if c.External { req.Header.Add("X-External-Client", "1") } // Make the request var resp *http.Response - if resp, err = this.Client.Do(req); err != nil { + if resp, err = c.Client.Do(req); err != nil { return nil, err } @@ -174,7 +190,7 @@ func (this ArvadosClient) CallRaw(method string, resource string, uuid string, a } defer resp.Body.Close() - return nil, newAPIServerError(this.ApiServer, resp) + return nil, newAPIServerError(c.ApiServer, resp) } func newAPIServerError(ServerAddress string, resp *http.Response) APIServerError { @@ -206,19 +222,20 @@ func newAPIServerError(ServerAddress string, resp *http.Response) APIServerError return ase } -// Access to a resource. +// Call an API endpoint and parse the JSON response into an object. // -// method - HTTP method, one of GET, HEAD, PUT, POST or DELETE -// resource - the arvados resource to act on -// uuid - the uuid of the specific item to access (may be empty) -// action - sub-action to take on the resource or uuid (may be empty) -// parameters - method parameters -// output - a map or annotated struct which is a legal target for encoding/json/Decoder -// return -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) Call(method string, resource string, uuid string, action string, parameters Dict, output interface{}) (err error) { - var reader io.ReadCloser - reader, err = this.CallRaw(method, resource, uuid, action, parameters) +// method - HTTP method: GET, HEAD, PUT, POST, PATCH or DELETE. +// resourceType - the type of arvados resource to act on (e.g., "collections", "pipeline_instances"). +// uuid - the uuid of the specific item to access. May be empty. +// action - API method name (e.g., "lock"). This is often empty if implied by method and uuid. +// parameters - method parameters. +// output - a map or annotated struct which is a legal target for encoding/json/Decoder. +// +// Returns a non-nil error if an error occurs making the API call, the +// API responds with a non-successful HTTP status, or an error occurs +// parsing the response body. +func (c ArvadosClient) Call(method string, resourceType string, uuid string, action string, parameters Dict, output interface{}) error { + reader, err := c.CallRaw(method, resourceType, uuid, action, parameters) if reader != nil { defer reader.Close() } @@ -235,74 +252,58 @@ func (this ArvadosClient) Call(method string, resource string, uuid string, acti return nil } -// Create a new instance of a resource. -// -// resource - the arvados resource on which to create an item -// parameters - method parameters -// output - a map or annotated struct which is a legal target for encoding/json/Decoder -// return -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) Create(resource string, parameters Dict, output interface{}) (err error) { - return this.Call("POST", resource, "", "", parameters, output) +// Create a new resource. See Call for argument descriptions. +func (c ArvadosClient) Create(resourceType string, parameters Dict, output interface{}) error { + return c.Call("POST", resourceType, "", "", parameters, output) } -// Delete an instance of a resource. -// -// resource - the arvados resource on which to delete an item -// uuid - the item to delete -// parameters - method parameters -// output - a map or annotated struct which is a legal target for encoding/json/Decoder -// return -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) Delete(resource string, uuid string, parameters Dict, output interface{}) (err error) { - return this.Call("DELETE", resource, uuid, "", parameters, output) +// Delete a resource. See Call for argument descriptions. +func (c ArvadosClient) Delete(resource string, uuid string, parameters Dict, output interface{}) (err error) { + return c.Call("DELETE", resource, uuid, "", parameters, output) } -// Update fields of an instance of a resource. -// -// resource - the arvados resource on which to update the item -// uuid - the item to update -// parameters - method parameters -// output - a map or annotated struct which is a legal target for encoding/json/Decoder -// return -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) Update(resource string, uuid string, parameters Dict, output interface{}) (err error) { - return this.Call("PUT", resource, uuid, "", parameters, output) +// Modify attributes of a resource. See Call for argument descriptions. +func (c ArvadosClient) Update(resourceType string, uuid string, parameters Dict, output interface{}) (err error) { + return c.Call("PUT", resourceType, uuid, "", parameters, output) } -// List the instances of a resource -// -// resource - the arvados resource on which to list -// parameters - method parameters -// output - a map or annotated struct which is a legal target for encoding/json/Decoder -// return -// err - error accessing the resource, or nil if no error -func (this ArvadosClient) List(resource string, parameters Dict, output interface{}) (err error) { - return this.Call("GET", resource, "", "", parameters, output) +// Get a resource. See Call for argument descriptions. +func (c ArvadosClient) Get(resourceType string, uuid string, parameters Dict, output interface{}) (err error) { + if !UUIDMatch(uuid) && !(resourceType == "collections" && PDHMatch(uuid)) { + // No object has uuid == "": there is no need to make + // an API call. Furthermore, the HTTP request for such + // an API call would be "GET /arvados/v1/type/", which + // is liable to be misinterpreted as the List API. + return ErrInvalidArgument + } + return c.Call("GET", resourceType, uuid, "", parameters, output) } -// API Discovery -// -// parameter - name of parameter to be discovered -// return -// value - value of the discovered parameter -// err - error accessing the resource, or nil if no error -var API_DISCOVERY_RESOURCE string = "discovery/v1/apis/arvados/v1/rest" - -func (this *ArvadosClient) Discovery(parameter string) (value interface{}, err error) { - if len(this.DiscoveryDoc) == 0 { - this.DiscoveryDoc = make(Dict) - err = this.Call("GET", API_DISCOVERY_RESOURCE, "", "", nil, &this.DiscoveryDoc) +// List resources of a given type. See Call for argument descriptions. +func (c ArvadosClient) List(resource string, parameters Dict, output interface{}) (err error) { + return c.Call("GET", resource, "", "", parameters, output) +} + +const API_DISCOVERY_RESOURCE = "discovery/v1/apis/arvados/v1/rest" + +// Discovery returns the value of the given parameter in the discovery +// document. Returns a non-nil error if the discovery document cannot +// be retrieved/decoded. Returns ErrInvalidArgument if the requested +// parameter is not found in the discovery document. +func (c *ArvadosClient) Discovery(parameter string) (value interface{}, err error) { + if len(c.DiscoveryDoc) == 0 { + c.DiscoveryDoc = make(Dict) + err = c.Call("GET", API_DISCOVERY_RESOURCE, "", "", nil, &c.DiscoveryDoc) if err != nil { return nil, err } } var found bool - value, found = this.DiscoveryDoc[parameter] + value, found = c.DiscoveryDoc[parameter] if found { return value, nil } else { - return value, errors.New("Not found") + return value, ErrInvalidArgument } }