X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/8d2aebfd3a0e4814b292659710386f949cafe092..3c0ef3fc0cdb3f56d90442cc389ce4c2c94e8831:/sdk/go/arvadosclient/arvadosclient.go diff --git a/sdk/go/arvadosclient/arvadosclient.go b/sdk/go/arvadosclient/arvadosclient.go index 99b08186a5..18e1074bf6 100644 --- a/sdk/go/arvadosclient/arvadosclient.go +++ b/sdk/go/arvadosclient/arvadosclient.go @@ -14,11 +14,23 @@ import ( "os" "regexp" "strings" + "time" ) -// 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") + +// A common failure mode is to reuse a keepalive connection that has been +// terminated (in a way that we can't detect) for being idle too long. +// POST and DELETE are not safe to retry automatically, so we minimize +// such failures by always using a new or recently active socket. +var MaxIdleConnectionDuration = 30 * time.Second // Indicates an error that was returned by the API server. type APIServerError struct { @@ -71,6 +83,8 @@ type ArvadosClient struct { // Discovery document DiscoveryDoc Dict + + lastClosedIdlesAt time.Time } // Create a new ArvadosClient, initialized with standard Arvados environment @@ -96,33 +110,26 @@ func MakeArvadosClient() (ac ArvadosClient, err error) { return ac, MissingArvadosApiToken } + ac.lastClosedIdlesAt = time.Now() + 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 +142,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 +164,23 @@ 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") } + // POST and DELETE are not safe to retry automatically, so we minimize + // such failures by always using a new or recently active socket + if method == "POST" || method == "DELETE" { + if time.Since(c.lastClosedIdlesAt) > MaxIdleConnectionDuration { + c.lastClosedIdlesAt = time.Now() + c.Client.Transport.(*http.Transport).CloseIdleConnections() + } + } + // 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 +189,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 +221,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 +251,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 } }