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/{uuid}/contents", ""}
  59         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/shared", ""}
  60         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  61         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  62         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  63         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  64         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  65         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  66         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  67         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  68         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  69         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  70         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  71         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  72         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  73         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  74         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  75         EndpointUserUpdateUUID                = APIEndpoint{"POST", "arvados/v1/users/{uuid}/update_uuid", ""}
  76         EndpointUserBatchUpdate               = APIEndpoint{"PATCH", "arvados/v1/users/batch_update", ""}
  77         EndpointUserAuthenticate              = APIEndpoint{"POST", "arvados/v1/users/authenticate", ""}
  78         EndpointAPIClientAuthorizationCurrent = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/current", ""}
  79 )
  80
  81 type ContainerSSHOptions struct {
  82         UUID          string `json:"uuid"`
  83         DetachKeys    string `json:"detach_keys"`
  84         LoginUsername string `json:"login_username"`
  85 }
  86
  87 type ContainerSSHConnection struct {
  88         Conn   net.Conn           `json:"-"`
  89         Bufrw  *bufio.ReadWriter  `json:"-"`
  90         Logger logrus.FieldLogger `json:"-"`
  91 }
  92
  93 type GetOptions struct {
  94         UUID         string   `json:"uuid,omitempty"`
  95         Select       []string `json:"select"`
  96         IncludeTrash bool     `json:"include_trash"`
  97         ForwardedFor string   `json:"forwarded_for,omitempty"`
  98         Remote       string   `json:"remote,omitempty"`
  99 }
 100
 101 type UntrashOptions struct {
 102         UUID             string `json:"uuid"`
 103         EnsureUniqueName bool   `json:"ensure_unique_name"`
 104 }
 105
 106 type ListOptions struct {
 107         ClusterID          string                 `json:"cluster_id"`
 108         Select             []string               `json:"select"`
 109         Filters            []Filter               `json:"filters"`
 110         Where              map[string]interface{} `json:"where"`
 111         Limit              int64                  `json:"limit"`
 112         Offset             int64                  `json:"offset"`
 113         Order              []string               `json:"order"`
 114         Distinct           bool                   `json:"distinct"`
 115         Count              string                 `json:"count"`
 116         IncludeTrash       bool                   `json:"include_trash"`
 117         IncludeOldVersions bool                   `json:"include_old_versions"`
 118         BypassFederation   bool                   `json:"bypass_federation"`
 119         ForwardedFor       string                 `json:"forwarded_for,omitempty"`
 120 }
 121
 122 type CreateOptions struct {
 123         ClusterID        string                 `json:"cluster_id"`
 124         EnsureUniqueName bool                   `json:"ensure_unique_name"`
 125         Select           []string               `json:"select"`
 126         Attrs            map[string]interface{} `json:"attrs"`
 127 }
 128
 129 type UpdateOptions struct {
 130         UUID             string                 `json:"uuid"`
 131         Attrs            map[string]interface{} `json:"attrs"`
 132         BypassFederation bool                   `json:"bypass_federation"`
 133 }
 134
 135 type ContentsOptions struct {
 136         UUID               string   `json:"uuid,omitempty"`
 137         Select             []string `json:"select"`
 138         Filters            []Filter `json:"filters"`
 139         Limit              int64    `json:"limit"`
 140         Offset             int64    `json:"offset"`
 141         Order              []string `json:"order"`
 142         Recursive          bool     `json:"recursive"`
 143         ExcludeHomeProject bool     `json:"exclude_home_project"`
 144 }
 145
 146 type SharedOptions struct {
 147         UUID    string   `json:"uuid,omitempty"`
 148         Select  []string `json:"select"`
 149         Filters []Filter `json:"filters"`
 150         Limit   int64    `json:"limit"`
 151         Offset  int64    `json:"offset"`
 152         Order   []string `json:"order"`
 153         Include string   `json:"include"`
 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 API interface {
 210         ConfigGet(ctx context.Context) (json.RawMessage, error)
 211         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 212         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 213         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 214         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 215         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 216         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 217         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 218         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 219         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 220         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 221         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 222         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 223         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 224         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 225         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 226         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 227         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 228         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 229         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 230         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 231         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 232         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 233         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 234         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 235         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 236         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 237         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 238         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 239         GroupContents(ctx context.Context, options ContentsOptions) (GroupList, error)
 240         GroupShared(ctx context.Context, options SharedOptions) (GroupList, error)
 241         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 242         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 243         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 244         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 245         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 246         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 247         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 248         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 249         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 250         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
 251         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 252         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 253         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 254         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 255         UserGet(ctx context.Context, options GetOptions) (User, error)
 256         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 257         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 258         UserList(ctx context.Context, options ListOptions) (UserList, error)
 259         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 260         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 261         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 262         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 263 }