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         EndpointGroupContents2                = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""}
  60         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
  61         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
  62         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
  63         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
  64         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
  65         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  66         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
  67         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
  68         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
  69         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  70         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
  71         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
  72         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
  73         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
  74         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
  75         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
  76         EndpointUserUpdateUUID                = APIEndpoint{"POST", "arvados/v1/users/{uuid}/update_uuid", ""}
  77         EndpointUserBatchUpdate               = APIEndpoint{"PATCH", "arvados/v1/users/batch_update", ""}
  78         EndpointUserAuthenticate              = APIEndpoint{"POST", "arvados/v1/users/authenticate", ""}
  79         EndpointAPIClientAuthorizationCurrent = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/current", ""}
  80 )
  81
  82 type ContainerSSHOptions struct {
  83         UUID          string `json:"uuid"`
  84         DetachKeys    string `json:"detach_keys"`
  85         LoginUsername string `json:"login_username"`
  86 }
  87
  88 type ContainerSSHConnection struct {
  89         Conn   net.Conn           `json:"-"`
  90         Bufrw  *bufio.ReadWriter  `json:"-"`
  91         Logger logrus.FieldLogger `json:"-"`
  92 }
  93
  94 type GetOptions struct {
  95         UUID         string   `json:"uuid,omitempty"`
  96         Select       []string `json:"select"`
  97         IncludeTrash bool     `json:"include_trash"`
  98         ForwardedFor string   `json:"forwarded_for,omitempty"`
  99         Remote       string   `json:"remote,omitempty"`
 100 }
 101
 102 type UntrashOptions struct {
 103         UUID             string `json:"uuid"`
 104         EnsureUniqueName bool   `json:"ensure_unique_name"`
 105 }
 106
 107 type ListOptions struct {
 108         ClusterID          string                 `json:"cluster_id"`
 109         Select             []string               `json:"select"`
 110         Filters            []Filter               `json:"filters"`
 111         Where              map[string]interface{} `json:"where"`
 112         Limit              int64                  `json:"limit"`
 113         Offset             int64                  `json:"offset"`
 114         Order              []string               `json:"order"`
 115         Distinct           bool                   `json:"distinct"`
 116         Count              string                 `json:"count"`
 117         IncludeTrash       bool                   `json:"include_trash"`
 118         IncludeOldVersions bool                   `json:"include_old_versions"`
 119         BypassFederation   bool                   `json:"bypass_federation"`
 120         ForwardedFor       string                 `json:"forwarded_for,omitempty"`
 121 }
 122
 123 type CreateOptions struct {
 124         ClusterID        string                 `json:"cluster_id"`
 125         EnsureUniqueName bool                   `json:"ensure_unique_name"`
 126         Select           []string               `json:"select"`
 127         Attrs            map[string]interface{} `json:"attrs"`
 128 }
 129
 130 type UpdateOptions struct {
 131         UUID             string                 `json:"uuid"`
 132         Attrs            map[string]interface{} `json:"attrs"`
 133         BypassFederation bool                   `json:"bypass_federation"`
 134 }
 135
 136 type ContentsOptions struct {
 137         UUID               string   `json:"uuid,omitempty"`
 138         Select             []string `json:"select"`
 139         Filters            []Filter `json:"filters"`
 140         Limit              int64    `json:"limit"`
 141         Offset             int64    `json:"offset"`
 142         Order              []string `json:"order"`
 143         Include            string   `json:"include"`
 144         Recursive          bool     `json:"recursive"`
 145         ExcludeHomeProject bool     `json:"exclude_home_project"`
 146 }
 147
 148 type SharedOptions struct {
 149         UUID    string   `json:"uuid,omitempty"`
 150         Select  []string `json:"select"`
 151         Filters []Filter `json:"filters"`
 152         Limit   int64    `json:"limit"`
 153         Offset  int64    `json:"offset"`
 154         Count   string   `json:"count"`
 155         Order   []string `json:"order"`
 156         Include string   `json:"include"`
 157 }
 158
 159 type UpdateUUIDOptions struct {
 160         UUID    string `json:"uuid"`
 161         NewUUID string `json:"new_uuid"`
 162 }
 163
 164 type UserActivateOptions struct {
 165         UUID string `json:"uuid"`
 166 }
 167
 168 type UserSetupOptions struct {
 169         UUID                  string                 `json:"uuid,omitempty"`
 170         Email                 string                 `json:"email,omitempty"`
 171         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
 172         RepoName              string                 `json:"repo_name,omitempty"`
 173         VMUUID                string                 `json:"vm_uuid,omitempty"`
 174         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
 175         Attrs                 map[string]interface{} `json:"attrs"`
 176 }
 177
 178 type UserMergeOptions struct {
 179         NewUserUUID       string `json:"new_user_uuid,omitempty"`
 180         OldUserUUID       string `json:"old_user_uuid,omitempty"`
 181         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
 182         NewUserToken      string `json:"new_user_token,omitempty"`
 183         RedirectToNewUser bool   `json:"redirect_to_new_user"`
 184 }
 185
 186 type UserBatchUpdateOptions struct {
 187         Updates map[string]map[string]interface{} `json:"updates"`
 188 }
 189
 190 type UserBatchUpdateResponse struct{}
 191
 192 type DeleteOptions struct {
 193         UUID string `json:"uuid"`
 194 }
 195
 196 type LoginOptions struct {
 197         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
 198         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
 199         Code     string `json:"code,omitempty"`   // OAuth2 callback code
 200         State    string `json:"state,omitempty"`  // OAuth2 callback state
 201 }
 202
 203 type UserAuthenticateOptions struct {
 204         Username string `json:"username,omitempty"` // PAM username
 205         Password string `json:"password,omitempty"` // PAM password
 206 }
 207
 208 type LogoutOptions struct {
 209         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
 210 }
 211
 212 type API interface {
 213         ConfigGet(ctx context.Context) (json.RawMessage, error)
 214         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
 215         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
 216         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
 217         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
 218         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
 219         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
 220         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 221         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
 222         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
 223         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
 224         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
 225         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
 226         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
 227         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
 228         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
 229         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
 230         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
 231         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
 232         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
 233         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
 234         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
 235         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
 236         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
 237         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
 238         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
 239         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
 240         GroupGet(ctx context.Context, options GetOptions) (Group, error)
 241         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
 242         GroupContents(ctx context.Context, options ContentsOptions) (ObjectList, error)
 243         GroupShared(ctx context.Context, options SharedOptions) (SharedGroupList, error)
 244         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
 245         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
 246         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
 247         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
 248         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
 249         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
 250         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
 251         UserCreate(ctx context.Context, options CreateOptions) (User, error)
 252         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
 253         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
 254         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
 255         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
 256         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
 257         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
 258         UserGet(ctx context.Context, options GetOptions) (User, error)
 259         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
 260         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
 261         UserList(ctx context.Context, options ListOptions) (UserList, error)
 262         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
 263         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
 264         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
 265         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
 266 }