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