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