sdk/go/arvados/api.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: Apache-2.0
   4
   5 package arvados
   6
   7 import (
   8         "bufio"
   9         "context"
  10         "encoding/json"
  11         "io"
  12         "net"
  13         "net/http"
  14
  15         "github.com/sirupsen/logrus"
  16 )
  17
  18 type APIEndpoint struct {
  19         Method string
  20         Path   string
  21         // "new attributes" key for create/update requests
  22         AttrsKey string
  23 }
  24
  25 var (
  26         EndpointConfigGet                     = APIEndpoint{"GET", "arvados/v1/config", ""}
  27         EndpointVocabularyGet                 = APIEndpoint{"GET", "arvados/v1/vocabulary", ""}
  28         EndpointLogin                         = APIEndpoint{"GET", "login", ""}
  29         EndpointLogout                        = APIEndpoint{"GET", "logout", ""}
  30         EndpointCollectionCreate              = APIEndpoint{"POST", "arvados/v1/collections", "collection"}
  31         EndpointCollectionUpdate              = APIEndpoint{"PATCH", "arvados/v1/collections/{uuid}", "collection"}
  32         EndpointCollectionGet                 = APIEndpoint{"GET", "arvados/v1/collections/{uuid}", ""}
  33         EndpointCollectionList                = APIEndpoint{"GET", "arvados/v1/collections", ""}
  34         EndpointCollectionProvenance          = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/provenance", ""}
  35         EndpointCollectionUsedBy              = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/used_by", ""}
  36         EndpointCollectionDelete              = APIEndpoint{"DELETE", "arvados/v1/collections/{uuid}", ""}
  37         EndpointCollectionTrash               = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/trash", ""}
  38         EndpointCollectionUntrash             = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/untrash", ""}
  39         EndpointSpecimenCreate                = APIEndpoint{"POST", "arvados/v1/specimens", "specimen"}
  40         EndpointSpecimenUpdate                = APIEndpoint{"PATCH", "arvados/v1/specimens/{uuid}", "specimen"}
  41         EndpointSpecimenGet                   = APIEndpoint{"GET", "arvados/v1/specimens/{uuid}", ""}
  42         EndpointSpecimenList                  = APIEndpoint{"GET", "arvados/v1/specimens", ""}
  43         EndpointSpecimenDelete                = APIEndpoint{"DELETE", "arvados/v1/specimens/{uuid}", ""}
  44         EndpointContainerCreate               = APIEndpoint{"POST", "arvados/v1/containers", "container"}
  45         EndpointContainerUpdate               = APIEndpoint{"PATCH", "arvados/v1/containers/{uuid}", "container"}
  46         EndpointContainerGet                  = APIEndpoint{"GET", "arvados/v1/containers/{uuid}", ""}
  47         EndpointContainerList                 = APIEndpoint{"GET", "arvados/v1/containers", ""}
  48         EndpointContainerDelete               = APIEndpoint{"DELETE", "arvados/v1/containers/{uuid}", ""}
  49         EndpointContainerLock                 = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/lock", ""}
  50         EndpointContainerUnlock               = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/unlock", ""}
  51         EndpointContainerSSH                  = APIEndpoint{"POST", "arvados/v1/connect/{uuid}/ssh", ""}            // move to /containers after #17014 fixes routing
  52         EndpointContainerGatewayTunnel        = APIEndpoint{"POST", "arvados/v1/connect/{uuid}/gateway_tunnel", ""} // move to /containers after #17014 fixes routing
  53         EndpointContainerRequestCreate        = APIEndpoint{"POST", "arvados/v1/container_requests", "container_request"}
  54         EndpointContainerRequestUpdate        = APIEndpoint{"PATCH", "arvados/v1/container_requests/{uuid}", "container_request"}
  55         EndpointContainerRequestGet           = APIEndpoint{"GET", "arvados/v1/container_requests/{uuid}", ""}
  56         EndpointContainerRequestList          = APIEndpoint{"GET", "arvados/v1/container_requests", ""}
  57         EndpointContainerRequestDelete        = APIEndpoint{"DELETE", "arvados/v1/container_requests/{uuid}", ""}
  58         EndpointGroupCreate                   = APIEndpoint{"POST", "arvados/v1/groups", "group"}
  59         EndpointGroupUpdate                   = APIEndpoint{"PATCH", "arvados/v1/groups/{uuid}", "group"}
  60         EndpointGroupGet                      = APIEndpoint{"GET", "arvados/v1/groups/{uuid}", ""}
  61         EndpointGroupList                     = APIEndpoint{"GET", "arvados/v1/groups", ""}
  62         EndpointGroupContents                 = APIEndpoint{"GET", "arvados/v1/groups/contents", ""}
  63         EndpointGroupContentsUUIDInPath       = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""} // Alternative HTTP route; client-side code should always use EndpointGroupContents instead
  64         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
  65         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  66         EndpointGroupTrash                    = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/trash", ""}
  67         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  68         EndpointLinkCreate                    = APIEndpoint{"POST", "arvados/v1/links", "link"}
  69         EndpointLinkUpdate                    = APIEndpoint{"PATCH", "arvados/v1/links/{uuid}", "link"}
  70         EndpointLinkGet                       = APIEndpoint{"GET", "arvados/v1/links/{uuid}", ""}
  71         EndpointLinkList                      = APIEndpoint{"GET", "arvados/v1/links", ""}
  72         EndpointLinkDelete                    = APIEndpoint{"DELETE", "arvados/v1/links/{uuid}", ""}
  73         EndpointSysTrashSweep                 = APIEndpoint{"POST", "sys/trash_sweep", ""}
  74         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  75         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  76         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  77         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  78         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  79         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  80         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  81         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  82         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  83         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  84         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  85         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  86         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  87         EndpointUserBatchUpdate               = APIEndpoint{"PATCH", "arvados/v1/users/batch_update", ""}
  88         EndpointUserAuthenticate              = APIEndpoint{"POST", "arvados/v1/users/authenticate", ""}
  89         EndpointAPIClientAuthorizationCurrent = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/current", ""}
  90         EndpointAPIClientAuthorizationCreate  = APIEndpoint{"POST", "arvados/v1/api_client_authorizations", "api_client_authorization"}
  91         EndpointAPIClientAuthorizationUpdate  = APIEndpoint{"PUT", "arvados/v1/api_client_authorizations/{uuid}", "api_client_authorization"}
  92         EndpointAPIClientAuthorizationList    = APIEndpoint{"GET", "arvados/v1/api_client_authorizations", ""}
  93         EndpointAPIClientAuthorizationDelete  = APIEndpoint{"DELETE", "arvados/v1/api_client_authorizations/{uuid}", ""}
  94         EndpointAPIClientAuthorizationGet     = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/{uuid}", ""}
  95 )
  96
  97 type ContainerSSHOptions struct {
  98         UUID          string `json:"uuid"`
  99         DetachKeys    string `json:"detach_keys"`
 100         LoginUsername string `json:"login_username"`
 101         NoForward     bool   `json:"no_forward"`
 102 }
 103
 104 type ConnectionResponse struct {
 105         Conn   net.Conn           `json:"-"`
 106         Bufrw  *bufio.ReadWriter  `json:"-"`
 107         Logger logrus.FieldLogger `json:"-"`
 108         Header http.Header        `json:"-"`
 109 }
 110
 111 type ContainerGatewayTunnelOptions struct {
 112         UUID       string `json:"uuid"`
 113         AuthSecret string `json:"auth_secret"`
 114 }
 115
 116 type GetOptions struct {
 117         UUID         string   `json:"uuid,omitempty"`
 118         Select       []string `json:"select"`
 119         IncludeTrash bool     `json:"include_trash"`
 120         ForwardedFor string   `json:"forwarded_for,omitempty"`
 121         Remote       string   `json:"remote,omitempty"`
 122 }
 123
 124 type UntrashOptions struct {
 125         UUID             string `json:"uuid"`
 126         EnsureUniqueName bool   `json:"ensure_unique_name"`
 127 }
 128
 129 type ListOptions struct {
 130         ClusterID          string                 `json:"cluster_id"`
 131         Select             []string               `json:"select"`
 132         Filters            []Filter               `json:"filters"`
 133         Where              map[string]interface{} `json:"where"`
 134         Limit              int64                  `json:"limit"`
 135         Offset             int64                  `json:"offset"`
 136         Order              []string               `json:"order"`
 137         Distinct           bool                   `json:"distinct"`
 138         Count              string                 `json:"count"`
 139         IncludeTrash       bool                   `json:"include_trash"`
 140         IncludeOldVersions bool                   `json:"include_old_versions"`
 141         BypassFederation   bool                   `json:"bypass_federation"`
 142         ForwardedFor       string                 `json:"forwarded_for,omitempty"`
 143         Include            string                 `json:"include"`
 144 }
 145
 146 type CreateOptions struct {
 147         ClusterID        string                 `json:"cluster_id"`
 148         EnsureUniqueName bool                   `json:"ensure_unique_name"`
 149         Select           []string               `json:"select"`
 150         Attrs            map[string]interface{} `json:"attrs"`
 151         // ReplaceFiles only applies when creating a collection.
 152         ReplaceFiles map[string]string `json:"replace_files"`
 153 }
 154
 155 type UpdateOptions struct {
 156         UUID             string                 `json:"uuid"`
 157         Attrs            map[string]interface{} `json:"attrs"`
 158         Select           []string               `json:"select"`
 159         BypassFederation bool                   `json:"bypass_federation"`
 160         // ReplaceFiles only applies when updating a collection.
 161         ReplaceFiles map[string]string `json:"replace_files"`
 162 }
 163
 164 type GroupContentsOptions struct {
 165         ClusterID          string   `json:"cluster_id"`
 166         UUID               string   `json:"uuid,omitempty"`
 167         Select             []string `json:"select"`
 168         Filters            []Filter `json:"filters"`
 169         Limit              int64    `json:"limit"`
 170         Offset             int64    `json:"offset"`
 171         Order              []string `json:"order"`
 172         Distinct           bool     `json:"distinct"`
 173         Count              string   `json:"count"`
 174         Include            string   `json:"include"`
 175         Recursive          bool     `json:"recursive"`
 176         IncludeTrash       bool     `json:"include_trash"`
 177         IncludeOldVersions bool     `json:"include_old_versions"`
 178         ExcludeHomeProject bool     `json:"exclude_home_project"`
 179 }
 180
 181 type UserActivateOptions struct {
 182         UUID string `json:"uuid"`
 183 }
 184
 185 type UserSetupOptions struct {
 186         UUID                  string                 `json:"uuid,omitempty"`
 187         Email                 string                 `json:"email,omitempty"`
 188         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 189         RepoName              string                 `json:"repo_name,omitempty"`
 190         VMUUID                string                 `json:"vm_uuid,omitempty"`
 191         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 192         Attrs                 map[string]interface{} `json:"attrs"`
 193 }
 194
 195 type UserMergeOptions struct {
 196         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 197         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 198         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 199         NewUserToken      string `json:"new_user_token,omitempty"`
 200         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 201 }
 202
 203 type UserBatchUpdateOptions struct {
 204         Updates map[string]map[string]interface{} `json:"updates"`
 205 }
 206
 207 type UserBatchUpdateResponse struct{}
 208
 209 type DeleteOptions struct {
 210         UUID string `json:"uuid"`
 211 }
 212
 213 type LoginOptions struct {
 214         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 215         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 216         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 217         State    string `json:"state,omitempty"`  // OAuth2 callback state
 218 }
 219
 220 type UserAuthenticateOptions struct {
 221         Username string `json:"username,omitempty"` // PAM username
 222         Password string `json:"password,omitempty"` // PAM password
 223 }
 224
 225 type LogoutOptions struct {
 226         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 227 }
 228
 229 type BlockWriteOptions struct {
 230         Hash           string
 231         Data           []byte
 232         Reader         io.Reader
 233         DataSize       int // Must be set if Data is nil.
 234         RequestID      string
 235         StorageClasses []string
 236         Replicas       int
 237         Attempts       int
 238 }
 239
 240 type BlockWriteResponse struct {
 241         Locator  string
 242         Replicas int
 243 }
 244
 245 type API interface {
 246         ConfigGet(ctx context.Context) (json.RawMessage, error)
 247         VocabularyGet(ctx context.Context) (Vocabulary, error)
 248         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 249         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 250         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 251         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 252         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 253         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 254         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 255         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 256         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 257         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 258         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 259         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 260         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 261         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 262         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 263         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 264         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 265         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 266         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ConnectionResponse, error)
 267         ContainerGatewayTunnel(ctx context.Context, options ContainerGatewayTunnelOptions) (ConnectionResponse, error)
 268         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 269         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 270         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 271         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 272         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 273         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 274         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 275         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 276         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 277         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 278         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 279         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 280         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 281         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 282         LinkCreate(ctx context.Context, options CreateOptions) (Link, error)
 283         LinkUpdate(ctx context.Context, options UpdateOptions) (Link, error)
 284         LinkGet(ctx context.Context, options GetOptions) (Link, error)
 285         LinkList(ctx context.Context, options ListOptions) (LinkList, error)
 286         LinkDelete(ctx context.Context, options DeleteOptions) (Link, error)
 287         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 288         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 289         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 290         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 291         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 292         SysTrashSweep(ctx context.Context, options struct{}) (struct{}, error)
 293         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 294         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 295         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 296         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 297         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 298         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 299         UserGet(ctx context.Context, options GetOptions) (User, error)
 300         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 301         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 302         UserList(ctx context.Context, options ListOptions) (UserList, error)
 303         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 304         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 305         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 306         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 307         APIClientAuthorizationCreate(ctx context.Context, options CreateOptions) (APIClientAuthorization, error)
 308         APIClientAuthorizationList(ctx context.Context, options ListOptions) (APIClientAuthorizationList, error)
 309         APIClientAuthorizationDelete(ctx context.Context, options DeleteOptions) (APIClientAuthorization, error)
 310         APIClientAuthorizationUpdate(ctx context.Context, options UpdateOptions) (APIClientAuthorization, error)
 311         APIClientAuthorizationGet(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 312 }