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