sdk/go/arvados/api.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: Apache-2.0
   4
   5 package arvados
   6
   7 import (
   8         "bufio"
   9         "context"
  10         "encoding/json"
  11         "io"
  12         "net"
  13
  14         "github.com/sirupsen/logrus"
  15 )
  16
  17 type APIEndpoint struct {
  18         Method string
  19         Path   string
  20         // "new attributes" key for create/update requests
  21         AttrsKey string
  22 }
  23
  24 var (
  25         EndpointConfigGet                     = APIEndpoint{"GET", "arvados/v1/config", ""}
  26         EndpointVocabularyGet                 = APIEndpoint{"GET", "arvados/v1/vocabulary", ""}
  27         EndpointLogin                         = APIEndpoint{"GET", "login", ""}
  28         EndpointLogout                        = APIEndpoint{"GET", "logout", ""}
  29         EndpointCollectionCreate              = APIEndpoint{"POST", "arvados/v1/collections", "collection"}
  30         EndpointCollectionUpdate              = APIEndpoint{"PATCH", "arvados/v1/collections/{uuid}", "collection"}
  31         EndpointCollectionGet                 = APIEndpoint{"GET", "arvados/v1/collections/{uuid}", ""}
  32         EndpointCollectionList                = APIEndpoint{"GET", "arvados/v1/collections", ""}
  33         EndpointCollectionProvenance          = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/provenance", ""}
  34         EndpointCollectionUsedBy              = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/used_by", ""}
  35         EndpointCollectionDelete              = APIEndpoint{"DELETE", "arvados/v1/collections/{uuid}", ""}
  36         EndpointCollectionTrash               = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/trash", ""}
  37         EndpointCollectionUntrash             = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/untrash", ""}
  38         EndpointSpecimenCreate                = APIEndpoint{"POST", "arvados/v1/specimens", "specimen"}
  39         EndpointSpecimenUpdate                = APIEndpoint{"PATCH", "arvados/v1/specimens/{uuid}", "specimen"}
  40         EndpointSpecimenGet                   = APIEndpoint{"GET", "arvados/v1/specimens/{uuid}", ""}
  41         EndpointSpecimenList                  = APIEndpoint{"GET", "arvados/v1/specimens", ""}
  42         EndpointSpecimenDelete                = APIEndpoint{"DELETE", "arvados/v1/specimens/{uuid}", ""}
  43         EndpointContainerCreate               = APIEndpoint{"POST", "arvados/v1/containers", "container"}
  44         EndpointContainerUpdate               = APIEndpoint{"PATCH", "arvados/v1/containers/{uuid}", "container"}
  45         EndpointContainerGet                  = APIEndpoint{"GET", "arvados/v1/containers/{uuid}", ""}
  46         EndpointContainerList                 = APIEndpoint{"GET", "arvados/v1/containers", ""}
  47         EndpointContainerDelete               = APIEndpoint{"DELETE", "arvados/v1/containers/{uuid}", ""}
  48         EndpointContainerLock                 = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/lock", ""}
  49         EndpointContainerUnlock               = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/unlock", ""}
  50         EndpointContainerSSH                  = APIEndpoint{"GET", "arvados/v1/connect/{uuid}/ssh", ""} // move to /containers after #17014 fixes routing
  51         EndpointContainerRequestCreate        = APIEndpoint{"POST", "arvados/v1/container_requests", "container_request"}
  52         EndpointContainerRequestUpdate        = APIEndpoint{"PATCH", "arvados/v1/container_requests/{uuid}", "container_request"}
  53         EndpointContainerRequestGet           = APIEndpoint{"GET", "arvados/v1/container_requests/{uuid}", ""}
  54         EndpointContainerRequestList          = APIEndpoint{"GET", "arvados/v1/container_requests", ""}
  55         EndpointContainerRequestDelete        = APIEndpoint{"DELETE", "arvados/v1/container_requests/{uuid}", ""}
  56         EndpointGroupCreate                   = APIEndpoint{"POST", "arvados/v1/groups", "group"}
  57         EndpointGroupUpdate                   = APIEndpoint{"PATCH", "arvados/v1/groups/{uuid}", "group"}
  58         EndpointGroupGet                      = APIEndpoint{"GET", "arvados/v1/groups/{uuid}", ""}
  59         EndpointGroupList                     = APIEndpoint{"GET", "arvados/v1/groups", ""}
  60         EndpointGroupContents                 = APIEndpoint{"GET", "arvados/v1/groups/contents", ""}
  61         EndpointGroupContentsUUIDInPath       = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""} // Alternative HTTP route; client-side code should always use EndpointGroupContents instead
  62         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
  63         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  64         EndpointGroupTrash                    = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/trash", ""}
  65         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  66         EndpointLinkCreate                    = APIEndpoint{"POST", "arvados/v1/links", "link"}
  67         EndpointLinkUpdate                    = APIEndpoint{"PATCH", "arvados/v1/links/{uuid}", "link"}
  68         EndpointLinkGet                       = APIEndpoint{"GET", "arvados/v1/links/{uuid}", ""}
  69         EndpointLinkList                      = APIEndpoint{"GET", "arvados/v1/links", ""}
  70         EndpointLinkDelete                    = APIEndpoint{"DELETE", "arvados/v1/links/{uuid}", ""}
  71         EndpointSysTrashSweep                 = APIEndpoint{"POST", "sys/trash_sweep", ""}
  72         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  73         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  74         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  75         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  76         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  77         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  78         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  79         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  80         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  81         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  82         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  83         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  84         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  85         EndpointUserBatchUpdate               = APIEndpoint{"PATCH", "arvados/v1/users/batch_update", ""}
  86         EndpointUserAuthenticate              = APIEndpoint{"POST", "arvados/v1/users/authenticate", ""}
  87         EndpointAPIClientAuthorizationCurrent = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/current", ""}
  88 )
  89
  90 type ContainerSSHOptions struct {
  91         UUID          string `json:"uuid"`
  92         DetachKeys    string `json:"detach_keys"`
  93         LoginUsername string `json:"login_username"`
  94 }
  95
  96 type ContainerSSHConnection struct {
  97         Conn   net.Conn           `json:"-"`
  98         Bufrw  *bufio.ReadWriter  `json:"-"`
  99         Logger logrus.FieldLogger `json:"-"`
 100 }
 101
 102 type GetOptions struct {
 103         UUID         string   `json:"uuid,omitempty"`
 104         Select       []string `json:"select"`
 105         IncludeTrash bool     `json:"include_trash"`
 106         ForwardedFor string   `json:"forwarded_for,omitempty"`
 107         Remote       string   `json:"remote,omitempty"`
 108 }
 109
 110 type UntrashOptions struct {
 111         UUID             string `json:"uuid"`
 112         EnsureUniqueName bool   `json:"ensure_unique_name"`
 113 }
 114
 115 type ListOptions struct {
 116         ClusterID          string                 `json:"cluster_id"`
 117         Select             []string               `json:"select"`
 118         Filters            []Filter               `json:"filters"`
 119         Where              map[string]interface{} `json:"where"`
 120         Limit              int64                  `json:"limit"`
 121         Offset             int64                  `json:"offset"`
 122         Order              []string               `json:"order"`
 123         Distinct           bool                   `json:"distinct"`
 124         Count              string                 `json:"count"`
 125         IncludeTrash       bool                   `json:"include_trash"`
 126         IncludeOldVersions bool                   `json:"include_old_versions"`
 127         BypassFederation   bool                   `json:"bypass_federation"`
 128         ForwardedFor       string                 `json:"forwarded_for,omitempty"`
 129         Include            string                 `json:"include"`
 130 }
 131
 132 type CreateOptions struct {
 133         ClusterID        string                 `json:"cluster_id"`
 134         EnsureUniqueName bool                   `json:"ensure_unique_name"`
 135         Select           []string               `json:"select"`
 136         Attrs            map[string]interface{} `json:"attrs"`
 137 }
 138
 139 type UpdateOptions struct {
 140         UUID             string                 `json:"uuid"`
 141         Attrs            map[string]interface{} `json:"attrs"`
 142         Select           []string               `json:"select"`
 143         BypassFederation bool                   `json:"bypass_federation"`
 144 }
 145
 146 type GroupContentsOptions struct {
 147         ClusterID          string   `json:"cluster_id"`
 148         UUID               string   `json:"uuid,omitempty"`
 149         Select             []string `json:"select"`
 150         Filters            []Filter `json:"filters"`
 151         Limit              int64    `json:"limit"`
 152         Offset             int64    `json:"offset"`
 153         Order              []string `json:"order"`
 154         Distinct           bool     `json:"distinct"`
 155         Count              string   `json:"count"`
 156         Include            string   `json:"include"`
 157         Recursive          bool     `json:"recursive"`
 158         IncludeTrash       bool     `json:"include_trash"`
 159         IncludeOldVersions bool     `json:"include_old_versions"`
 160         ExcludeHomeProject bool     `json:"exclude_home_project"`
 161 }
 162
 163 type UserActivateOptions struct {
 164         UUID string `json:"uuid"`
 165 }
 166
 167 type UserSetupOptions struct {
 168         UUID                  string                 `json:"uuid,omitempty"`
 169         Email                 string                 `json:"email,omitempty"`
 170         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 171         RepoName              string                 `json:"repo_name,omitempty"`
 172         VMUUID                string                 `json:"vm_uuid,omitempty"`
 173         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 174         Attrs                 map[string]interface{} `json:"attrs"`
 175 }
 176
 177 type UserMergeOptions struct {
 178         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 179         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 180         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 181         NewUserToken      string `json:"new_user_token,omitempty"`
 182         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 183 }
 184
 185 type UserBatchUpdateOptions struct {
 186         Updates map[string]map[string]interface{} `json:"updates"`
 187 }
 188
 189 type UserBatchUpdateResponse struct{}
 190
 191 type DeleteOptions struct {
 192         UUID string `json:"uuid"`
 193 }
 194
 195 type LoginOptions struct {
 196         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 197         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 198         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 199         State    string `json:"state,omitempty"`  // OAuth2 callback state
 200 }
 201
 202 type UserAuthenticateOptions struct {
 203         Username string `json:"username,omitempty"` // PAM username
 204         Password string `json:"password,omitempty"` // PAM password
 205 }
 206
 207 type LogoutOptions struct {
 208         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 209 }
 210
 211 type BlockWriteOptions struct {
 212         Hash           string
 213         Data           []byte
 214         Reader         io.Reader
 215         DataSize       int // Must be set if Data is nil.
 216         RequestID      string
 217         StorageClasses []string
 218         Replicas       int
 219         Attempts       int
 220 }
 221
 222 type BlockWriteResponse struct {
 223         Locator  string
 224         Replicas int
 225 }
 226
 227 type API interface {
 228         ConfigGet(ctx context.Context) (json.RawMessage, error)
 229         VocabularyGet(ctx context.Context) (Vocabulary, error)
 230         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 231         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 232         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 233         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 234         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 235         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 236         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 237         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 238         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 239         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 240         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 241         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 242         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 243         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 244         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 245         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 246         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 247         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 248         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 249         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 250         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 251         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 252         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 253         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 254         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 255         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 256         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 257         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 258         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 259         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 260         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 261         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 262         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 263         LinkCreate(ctx context.Context, options CreateOptions) (Link, error)
 264         LinkUpdate(ctx context.Context, options UpdateOptions) (Link, error)
 265         LinkGet(ctx context.Context, options GetOptions) (Link, error)
 266         LinkList(ctx context.Context, options ListOptions) (LinkList, error)
 267         LinkDelete(ctx context.Context, options DeleteOptions) (Link, error)
 268         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 269         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 270         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 271         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 272         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 273         SysTrashSweep(ctx context.Context, options struct{}) (struct{}, error)
 274         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 275         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 276         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 277         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 278         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 279         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 280         UserGet(ctx context.Context, options GetOptions) (User, error)
 281         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 282         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 283         UserList(ctx context.Context, options ListOptions) (UserList, error)
 284         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 285         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 286         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 287         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 288 }