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