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