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