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         BypassFederation bool                   `json:"bypass_federation"`
 137 }
 138
 139 type GroupContentsOptions struct {
 140         ClusterID          string   `json:"cluster_id"`
 141         UUID               string   `json:"uuid,omitempty"`
 142         Select             []string `json:"select"`
 143         Filters            []Filter `json:"filters"`
 144         Limit              int64    `json:"limit"`
 145         Offset             int64    `json:"offset"`
 146         Order              []string `json:"order"`
 147         Distinct           bool     `json:"distinct"`
 148         Count              string   `json:"count"`
 149         Include            string   `json:"include"`
 150         Recursive          bool     `json:"recursive"`
 151         IncludeTrash       bool     `json:"include_trash"`
 152         IncludeOldVersions bool     `json:"include_old_versions"`
 153         ExcludeHomeProject bool     `json:"exclude_home_project"`
 154 }
 155
 156 type UpdateUUIDOptions struct {
 157         UUID    string `json:"uuid"`
 158         NewUUID string `json:"new_uuid"`
 159 }
 160
 161 type UserActivateOptions struct {
 162         UUID string `json:"uuid"`
 163 }
 164
 165 type UserSetupOptions struct {
 166         UUID                  string                 `json:"uuid,omitempty"`
 167         Email                 string                 `json:"email,omitempty"`
 168         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 169         RepoName              string                 `json:"repo_name,omitempty"`
 170         VMUUID                string                 `json:"vm_uuid,omitempty"`
 171         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 172         Attrs                 map[string]interface{} `json:"attrs"`
 173 }
 174
 175 type UserMergeOptions struct {
 176         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 177         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 178         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 179         NewUserToken      string `json:"new_user_token,omitempty"`
 180         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 181 }
 182
 183 type UserBatchUpdateOptions struct {
 184         Updates map[string]map[string]interface{} `json:"updates"`
 185 }
 186
 187 type UserBatchUpdateResponse struct{}
 188
 189 type DeleteOptions struct {
 190         UUID string `json:"uuid"`
 191 }
 192
 193 type LoginOptions struct {
 194         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 195         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 196         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 197         State    string `json:"state,omitempty"`  // OAuth2 callback state
 198 }
 199
 200 type UserAuthenticateOptions struct {
 201         Username string `json:"username,omitempty"` // PAM username
 202         Password string `json:"password,omitempty"` // PAM password
 203 }
 204
 205 type LogoutOptions struct {
 206         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 207 }
 208
 209 type BlockWriteOptions struct {
 210         Hash           string
 211         Data           []byte
 212         Reader         io.Reader
 213         DataSize       int // Must be set if Data is nil.
 214         RequestID      string
 215         StorageClasses []string
 216         Replicas       int
 217         Attempts       int
 218 }
 219
 220 type BlockWriteResponse struct {
 221         Locator  string
 222         Replicas int
 223 }
 224
 225 type API interface {
 226         ConfigGet(ctx context.Context) (json.RawMessage, error)
 227         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 228         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 229         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 230         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 231         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 232         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 233         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 234         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 235         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 236         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 237         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 238         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 239         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 240         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 241         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 242         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 243         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 244         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 245         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 246         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 247         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 248         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 249         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 250         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 251         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 252         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 253         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 254         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 255         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 256         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 257         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 258         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 259         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 260         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 261         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 262         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 263         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 264         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 265         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 266         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 267         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
 268         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 269         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 270         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 271         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 272         UserGet(ctx context.Context, options GetOptions) (User, error)
 273         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 274         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 275         UserList(ctx context.Context, options ListOptions) (UserList, error)
 276         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 277         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 278         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 279         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 280 }