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