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