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