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