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         EndpointLogin                         = APIEndpoint{"GET", "login", ""}
  27         EndpointLogout                        = APIEndpoint{"GET", "logout", ""}
  28         EndpointCollectionCreate              = APIEndpoint{"POST", "arvados/v1/collections", "collection"}
  29         EndpointCollectionUpdate              = APIEndpoint{"PATCH", "arvados/v1/collections/{uuid}", "collection"}
  30         EndpointCollectionGet                 = APIEndpoint{"GET", "arvados/v1/collections/{uuid}", ""}
  31         EndpointCollectionList                = APIEndpoint{"GET", "arvados/v1/collections", ""}
  32         EndpointCollectionProvenance          = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/provenance", ""}
  33         EndpointCollectionUsedBy              = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/used_by", ""}
  34         EndpointCollectionDelete              = APIEndpoint{"DELETE", "arvados/v1/collections/{uuid}", ""}
  35         EndpointCollectionTrash               = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/trash", ""}
  36         EndpointCollectionUntrash             = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/untrash", ""}
  37         EndpointSpecimenCreate                = APIEndpoint{"POST", "arvados/v1/specimens", "specimen"}
  38         EndpointSpecimenUpdate                = APIEndpoint{"PATCH", "arvados/v1/specimens/{uuid}", "specimen"}
  39         EndpointSpecimenGet                   = APIEndpoint{"GET", "arvados/v1/specimens/{uuid}", ""}
  40         EndpointSpecimenList                  = APIEndpoint{"GET", "arvados/v1/specimens", ""}
  41         EndpointSpecimenDelete                = APIEndpoint{"DELETE", "arvados/v1/specimens/{uuid}", ""}
  42         EndpointContainerCreate               = APIEndpoint{"POST", "arvados/v1/containers", "container"}
  43         EndpointContainerUpdate               = APIEndpoint{"PATCH", "arvados/v1/containers/{uuid}", "container"}
  44         EndpointContainerGet                  = APIEndpoint{"GET", "arvados/v1/containers/{uuid}", ""}
  45         EndpointContainerList                 = APIEndpoint{"GET", "arvados/v1/containers", ""}
  46         EndpointContainerDelete               = APIEndpoint{"DELETE", "arvados/v1/containers/{uuid}", ""}
  47         EndpointContainerLock                 = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/lock", ""}
  48         EndpointContainerUnlock               = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/unlock", ""}
  49         EndpointContainerSSH                  = APIEndpoint{"GET", "arvados/v1/connect/{uuid}/ssh", ""} // move to /containers after #17014 fixes routing
  50         EndpointContainerRequestCreate        = APIEndpoint{"POST", "arvados/v1/container_requests", "container_request"}
  51         EndpointContainerRequestUpdate        = APIEndpoint{"PATCH", "arvados/v1/container_requests/{uuid}", "container_request"}
  52         EndpointContainerRequestGet           = APIEndpoint{"GET", "arvados/v1/container_requests/{uuid}", ""}
  53         EndpointContainerRequestList          = APIEndpoint{"GET", "arvados/v1/container_requests", ""}
  54         EndpointContainerRequestDelete        = APIEndpoint{"DELETE", "arvados/v1/container_requests/{uuid}", ""}
  55         EndpointGroupCreate                   = APIEndpoint{"POST", "arvados/v1/groups", "group"}
  56         EndpointGroupUpdate                   = APIEndpoint{"PATCH", "arvados/v1/groups/{uuid}", "group"}
  57         EndpointGroupGet                      = APIEndpoint{"GET", "arvados/v1/groups/{uuid}", ""}
  58         EndpointGroupList                     = APIEndpoint{"GET", "arvados/v1/groups", ""}
  59         EndpointGroupContents                 = APIEndpoint{"GET", "arvados/v1/groups/contents", ""}
  60         EndpointGroupContentsUUIDInPath       = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""} // Alternative HTTP route; client-side code should always use EndpointGroupContents instead
  61         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
  62         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  63         EndpointGroupTrash                    = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/trash", ""}
  64         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  65         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  66         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  67         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  68         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  69         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  70         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  71         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  72         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  73         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  74         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  75         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  76         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  77         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  78         EndpointUserUpdateUUID                = APIEndpoint{"POST", "arvados/v1/users/{uuid}/update_uuid", ""}
  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 UpdateUUIDOptions struct {
 158         UUID    string `json:"uuid"`
 159         NewUUID string `json:"new_uuid"`
 160 }
 161
 162 type UserActivateOptions struct {
 163         UUID string `json:"uuid"`
 164 }
 165
 166 type UserSetupOptions struct {
 167         UUID                  string                 `json:"uuid,omitempty"`
 168         Email                 string                 `json:"email,omitempty"`
 169         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 170         RepoName              string                 `json:"repo_name,omitempty"`
 171         VMUUID                string                 `json:"vm_uuid,omitempty"`
 172         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 173         Attrs                 map[string]interface{} `json:"attrs"`
 174 }
 175
 176 type UserMergeOptions struct {
 177         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 178         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 179         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 180         NewUserToken      string `json:"new_user_token,omitempty"`
 181         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 182 }
 183
 184 type UserBatchUpdateOptions struct {
 185         Updates map[string]map[string]interface{} `json:"updates"`
 186 }
 187
 188 type UserBatchUpdateResponse struct{}
 189
 190 type DeleteOptions struct {
 191         UUID string `json:"uuid"`
 192 }
 193
 194 type LoginOptions struct {
 195         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 196         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 197         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 198         State    string `json:"state,omitempty"`  // OAuth2 callback state
 199 }
 200
 201 type UserAuthenticateOptions struct {
 202         Username string `json:"username,omitempty"` // PAM username
 203         Password string `json:"password,omitempty"` // PAM password
 204 }
 205
 206 type LogoutOptions struct {
 207         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 208 }
 209
 210 type BlockWriteOptions struct {
 211         Hash           string
 212         Data           []byte
 213         Reader         io.Reader
 214         DataSize       int // Must be set if Data is nil.
 215         RequestID      string
 216         StorageClasses []string
 217         Replicas       int
 218         Attempts       int
 219 }
 220
 221 type BlockWriteResponse struct {
 222         Locator  string
 223         Replicas int
 224 }
 225
 226 type API interface {
 227         ConfigGet(ctx context.Context) (json.RawMessage, error)
 228         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 229         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 230         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 231         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 232         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 233         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 234         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 235         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 236         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 237         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 238         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 239         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 240         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 241         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 242         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 243         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 244         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 245         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 246         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 247         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 248         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 249         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 250         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 251         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 252         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 253         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 254         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 255         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 256         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 257         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 258         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 259         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 260         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 261         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 262         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 263         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 264         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 265         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 266         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 267         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 268         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
 269         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 270         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 271         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 272         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 273         UserGet(ctx context.Context, options GetOptions) (User, error)
 274         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 275         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 276         UserList(ctx context.Context, options ListOptions) (UserList, error)
 277         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 278         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 279         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 280         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 281 }