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