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