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         "net"
  12
  13         "github.com/sirupsen/logrus"
  14 )
  15
  16 type APIEndpoint struct {
  17         Method string
  18         Path   string
  19         // "new attributes" key for create/update requests
  20         AttrsKey string
  21 }
  22
  23 var (
  24         EndpointConfigGet                     = APIEndpoint{"GET", "arvados/v1/config", ""}
  25         EndpointLogin                         = APIEndpoint{"GET", "login", ""}
  26         EndpointLogout                        = APIEndpoint{"GET", "logout", ""}
  27         EndpointCollectionCreate              = APIEndpoint{"POST", "arvados/v1/collections", "collection"}
  28         EndpointCollectionUpdate              = APIEndpoint{"PATCH", "arvados/v1/collections/{uuid}", "collection"}
  29         EndpointCollectionGet                 = APIEndpoint{"GET", "arvados/v1/collections/{uuid}", ""}
  30         EndpointCollectionList                = APIEndpoint{"GET", "arvados/v1/collections", ""}
  31         EndpointCollectionProvenance          = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/provenance", ""}
  32         EndpointCollectionUsedBy              = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/used_by", ""}
  33         EndpointCollectionDelete              = APIEndpoint{"DELETE", "arvados/v1/collections/{uuid}", ""}
  34         EndpointCollectionTrash               = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/trash", ""}
  35         EndpointCollectionUntrash             = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/untrash", ""}
  36         EndpointSpecimenCreate                = APIEndpoint{"POST", "arvados/v1/specimens", "specimen"}
  37         EndpointSpecimenUpdate                = APIEndpoint{"PATCH", "arvados/v1/specimens/{uuid}", "specimen"}
  38         EndpointSpecimenGet                   = APIEndpoint{"GET", "arvados/v1/specimens/{uuid}", ""}
  39         EndpointSpecimenList                  = APIEndpoint{"GET", "arvados/v1/specimens", ""}
  40         EndpointSpecimenDelete                = APIEndpoint{"DELETE", "arvados/v1/specimens/{uuid}", ""}
  41         EndpointContainerCreate               = APIEndpoint{"POST", "arvados/v1/containers", "container"}
  42         EndpointContainerUpdate               = APIEndpoint{"PATCH", "arvados/v1/containers/{uuid}", "container"}
  43         EndpointContainerGet                  = APIEndpoint{"GET", "arvados/v1/containers/{uuid}", ""}
  44         EndpointContainerList                 = APIEndpoint{"GET", "arvados/v1/containers", ""}
  45         EndpointContainerDelete               = APIEndpoint{"DELETE", "arvados/v1/containers/{uuid}", ""}
  46         EndpointContainerLock                 = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/lock", ""}
  47         EndpointContainerUnlock               = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/unlock", ""}
  48         EndpointContainerSSH                  = APIEndpoint{"GET", "arvados/v1/connect/{uuid}/ssh", ""} // move to /containers after #17014 fixes routing
  49         EndpointContainerRequestCreate        = APIEndpoint{"POST", "arvados/v1/container_requests", "container_request"}
  50         EndpointContainerRequestUpdate        = APIEndpoint{"PATCH", "arvados/v1/container_requests/{uuid}", "container_request"}
  51         EndpointContainerRequestGet           = APIEndpoint{"GET", "arvados/v1/container_requests/{uuid}", ""}
  52         EndpointContainerRequestList          = APIEndpoint{"GET", "arvados/v1/container_requests", ""}
  53         EndpointContainerRequestDelete        = APIEndpoint{"DELETE", "arvados/v1/container_requests/{uuid}", ""}
  54         EndpointGroupCreate                   = APIEndpoint{"POST", "arvados/v1/groups", "group"}
  55         EndpointGroupUpdate                   = APIEndpoint{"PATCH", "arvados/v1/groups/{uuid}", "group"}
  56         EndpointGroupGet                      = APIEndpoint{"GET", "arvados/v1/groups/{uuid}", ""}
  57         EndpointGroupList                     = APIEndpoint{"GET", "arvados/v1/groups", ""}
  58         EndpointGroupContents                 = APIEndpoint{"GET", "arvados/v1/groups/contents", ""}
  59         EndpointGroupContentsUUIDInPath       = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""} // Alternative HTTP route; client-side code should always use EndpointGroupContents instead
  60         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
  61         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  62         EndpointGroupTrash                    = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/trash", ""}
  63         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  64         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  65         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  66         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  67         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  68         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  69         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  70         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  71         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  72         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  73         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  74         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  75         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  76         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  77         EndpointUserUpdateUUID                = APIEndpoint{"POST", "arvados/v1/users/{uuid}/update_uuid", ""}
  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         BypassFederation bool                   `json:"bypass_federation"`
 136 }
 137
 138 type GroupContentsOptions struct {
 139         UUID               string   `json:"uuid,omitempty"`
 140         Select             []string `json:"select"`
 141         Filters            []Filter `json:"filters"`
 142         Limit              int64    `json:"limit"`
 143         Offset             int64    `json:"offset"`
 144         Order              []string `json:"order"`
 145         Distinct           bool     `json:"distinct"`
 146         Count              string   `json:"count"`
 147         Include            string   `json:"include"`
 148         Recursive          bool     `json:"recursive"`
 149         IncludeTrash       bool     `json:"include_trash"`
 150         IncludeOldVersions bool     `json:"include_old_versions"`
 151         ExcludeHomeProject bool     `json:"exclude_home_project"`
 152 }
 153
 154 type UpdateUUIDOptions struct {
 155         UUID    string `json:"uuid"`
 156         NewUUID string `json:"new_uuid"`
 157 }
 158
 159 type UserActivateOptions struct {
 160         UUID string `json:"uuid"`
 161 }
 162
 163 type UserSetupOptions struct {
 164         UUID                  string                 `json:"uuid,omitempty"`
 165         Email                 string                 `json:"email,omitempty"`
 166         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 167         RepoName              string                 `json:"repo_name,omitempty"`
 168         VMUUID                string                 `json:"vm_uuid,omitempty"`
 169         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 170         Attrs                 map[string]interface{} `json:"attrs"`
 171 }
 172
 173 type UserMergeOptions struct {
 174         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 175         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 176         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 177         NewUserToken      string `json:"new_user_token,omitempty"`
 178         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 179 }
 180
 181 type UserBatchUpdateOptions struct {
 182         Updates map[string]map[string]interface{} `json:"updates"`
 183 }
 184
 185 type UserBatchUpdateResponse struct{}
 186
 187 type DeleteOptions struct {
 188         UUID string `json:"uuid"`
 189 }
 190
 191 type LoginOptions struct {
 192         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 193         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 194         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 195         State    string `json:"state,omitempty"`  // OAuth2 callback state
 196 }
 197
 198 type UserAuthenticateOptions struct {
 199         Username string `json:"username,omitempty"` // PAM username
 200         Password string `json:"password,omitempty"` // PAM password
 201 }
 202
 203 type LogoutOptions struct {
 204         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 205 }
 206
 207 type API interface {
 208         ConfigGet(ctx context.Context) (json.RawMessage, error)
 209         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 210         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 211         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 212         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 213         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 214         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 215         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 216         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 217         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 218         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 219         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 220         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 221         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 222         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 223         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 224         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 225         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 226         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 227         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 228         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 229         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 230         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 231         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 232         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 233         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 234         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 235         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 236         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 237         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
 238         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
 239         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 240         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
 241         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 242         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 243         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 244         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 245         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 246         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 247         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 248         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 249         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
 250         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 251         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 252         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 253         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 254         UserGet(ctx context.Context, options GetOptions) (User, error)
 255         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 256         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 257         UserList(ctx context.Context, options ListOptions) (UserList, error)
 258         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 259         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 260         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 261         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 262 }