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 and ReplaceSegments only apply when creating a
 164         // collection.
 165         ReplaceFiles    map[string]string             `json:"replace_files"`
 166         ReplaceSegments map[BlockSegment]BlockSegment `json:"replace_segments"`
 167 }
 168
 169 type UpdateOptions struct {
 170         UUID             string                 `json:"uuid"`
 171         Attrs            map[string]interface{} `json:"attrs"`
 172         Select           []string               `json:"select"`
 173         BypassFederation bool                   `json:"bypass_federation"`
 174         // ReplaceFiles and ReplaceSegments only apply when updating a
 175         // collection.
 176         ReplaceFiles    map[string]string             `json:"replace_files"`
 177         ReplaceSegments map[BlockSegment]BlockSegment `json:"replace_segments"`
 178 }
 179
 180 type GroupContentsOptions struct {
 181         ClusterID          string   `json:"cluster_id"`
 182         UUID               string   `json:"uuid,omitempty"`
 183         Select             []string `json:"select"`
 184         Filters            []Filter `json:"filters"`
 185         Limit              int64    `json:"limit"`
 186         Offset             int64    `json:"offset"`
 187         Order              []string `json:"order"`
 188         Distinct           bool     `json:"distinct"`
 189         Count              string   `json:"count"`
 190         Include            []string `json:"include"`
 191         Recursive          bool     `json:"recursive"`
 192         IncludeTrash       bool     `json:"include_trash"`
 193         IncludeOldVersions bool     `json:"include_old_versions"`
 194         ExcludeHomeProject bool     `json:"exclude_home_project"`
 195 }
 196
 197 type UserActivateOptions struct {
 198         UUID string `json:"uuid"`
 199 }
 200
 201 type UserSetupOptions struct {
 202         UUID                  string                 `json:"uuid,omitempty"`
 203         Email                 string                 `json:"email,omitempty"`
 204         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 205         RepoName              string                 `json:"repo_name,omitempty"`
 206         VMUUID                string                 `json:"vm_uuid,omitempty"`
 207         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 208         Attrs                 map[string]interface{} `json:"attrs"`
 209 }
 210
 211 type UserMergeOptions struct {
 212         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 213         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 214         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 215         NewUserToken      string `json:"new_user_token,omitempty"`
 216         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 217 }
 218
 219 type UserBatchUpdateOptions struct {
 220         Updates map[string]map[string]interface{} `json:"updates"`
 221 }
 222
 223 type UserBatchUpdateResponse struct{}
 224
 225 type DeleteOptions struct {
 226         UUID string `json:"uuid"`
 227 }
 228
 229 type LoginOptions struct {
 230         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 231         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 232         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 233         State    string `json:"state,omitempty"`  // OAuth2 callback state
 234 }
 235
 236 type UserAuthenticateOptions struct {
 237         Username string `json:"username,omitempty"` // PAM username
 238         Password string `json:"password,omitempty"` // PAM password
 239 }
 240
 241 type LogoutOptions struct {
 242         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 243 }
 244
 245 type BlockReadOptions struct {
 246         Locator      string
 247         WriteTo      io.Writer
 248         LocalLocator func(string)
 249 }
 250
 251 type BlockWriteOptions struct {
 252         Hash           string
 253         Data           []byte
 254         Reader         io.Reader // Must be set if Data is nil.
 255         DataSize       int       // Must be set if Data is nil.
 256         RequestID      string
 257         StorageClasses []string
 258         Replicas       int
 259         Attempts       int
 260 }
 261
 262 type BlockWriteResponse struct {
 263         Locator        string
 264         Replicas       int
 265         StorageClasses map[string]int
 266 }
 267
 268 type WebDAVOptions struct {
 269         Method string
 270         Path   string
 271         Header http.Header
 272 }
 273
 274 type ContainerLogOptions struct {
 275         UUID      string `json:"uuid"`
 276         NoForward bool   `json:"no_forward"`
 277         WebDAVOptions
 278 }
 279
 280 type RepackOptions struct {
 281         Underutilized bool
 282         CachedOnly    bool
 283         Full          bool
 284         DryRun        bool
 285 }
 286
 287 type API interface {
 288         ConfigGet(ctx context.Context) (json.RawMessage, error)
 289         VocabularyGet(ctx context.Context) (Vocabulary, error)
 290         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 291         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 292         AuthorizedKeyCreate(ctx context.Context, options CreateOptions) (AuthorizedKey, error)
 293         AuthorizedKeyUpdate(ctx context.Context, options UpdateOptions) (AuthorizedKey, error)
 294         AuthorizedKeyGet(ctx context.Context, options GetOptions) (AuthorizedKey, error)
 295         AuthorizedKeyList(ctx context.Context, options ListOptions) (AuthorizedKeyList, error)
 296         AuthorizedKeyDelete(ctx context.Context, options DeleteOptions) (AuthorizedKey, error)
 297         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 298         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 299         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 300         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 301         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 302         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 303         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 304         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 305         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 306         ComputedPermissionList(ctx context.Context, options ListOptions) (ComputedPermissionList, error)
 307         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 308         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 309         ContainerPriorityUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 310         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 311         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 312         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 313         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 314         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 315         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ConnectionResponse, error)
 316         ContainerGatewayTunnel(ctx context.Context, options ContainerGatewayTunnelOptions) (ConnectionResponse, error)
 317         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 318         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 319         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 320         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 321         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 322         ContainerRequestContainerStatus(ctx context.Context, options GetOptions) (ContainerStatus, error)
 323         ContainerRequestLog(ctx context.Context, options ContainerLogOptions) (http.Handler, error)
 324         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 325         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 326         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 327         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 328         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 329         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 330         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 331         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 332         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 333         LinkCreate(ctx context.Context, options CreateOptions) (Link, error)
 334         LinkUpdate(ctx context.Context, options UpdateOptions) (Link, error)
 335         LinkGet(ctx context.Context, options GetOptions) (Link, error)
 336         LinkList(ctx context.Context, options ListOptions) (LinkList, error)
 337         LinkDelete(ctx context.Context, options DeleteOptions) (Link, error)
 338         LogCreate(ctx context.Context, options CreateOptions) (Log, error)
 339         LogUpdate(ctx context.Context, options UpdateOptions) (Log, error)
 340         LogGet(ctx context.Context, options GetOptions) (Log, error)
 341         LogList(ctx context.Context, options ListOptions) (LogList, error)
 342         LogDelete(ctx context.Context, options DeleteOptions) (Log, error)
 343         SysTrashSweep(ctx context.Context, options struct{}) (struct{}, error)
 344         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 345         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 346         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 347         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 348         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 349         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 350         UserGet(ctx context.Context, options GetOptions) (User, error)
 351         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 352         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 353         UserList(ctx context.Context, options ListOptions) (UserList, error)
 354         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 355         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 356         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 357         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 358         APIClientAuthorizationCreate(ctx context.Context, options CreateOptions) (APIClientAuthorization, error)
 359         APIClientAuthorizationList(ctx context.Context, options ListOptions) (APIClientAuthorizationList, error)
 360         APIClientAuthorizationDelete(ctx context.Context, options DeleteOptions) (APIClientAuthorization, error)
 361         APIClientAuthorizationUpdate(ctx context.Context, options UpdateOptions) (APIClientAuthorization, error)
 362         APIClientAuthorizationGet(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 363         DiscoveryDocument(ctx context.Context) (DiscoveryDocument, error)
 364 }