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