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