17995: Merge branch 'main'
[arvados.git] / 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         "io"
12         "net"
13
14         "github.com/sirupsen/logrus"
15 )
16
17 type APIEndpoint struct {
18         Method string
19         Path   string
20         // "new attributes" key for create/update requests
21         AttrsKey string
22 }
23
24 var (
25         EndpointConfigGet                     = APIEndpoint{"GET", "arvados/v1/config", ""}
26         EndpointLogin                         = APIEndpoint{"GET", "login", ""}
27         EndpointLogout                        = APIEndpoint{"GET", "logout", ""}
28         EndpointCollectionCreate              = APIEndpoint{"POST", "arvados/v1/collections", "collection"}
29         EndpointCollectionUpdate              = APIEndpoint{"PATCH", "arvados/v1/collections/{uuid}", "collection"}
30         EndpointCollectionGet                 = APIEndpoint{"GET", "arvados/v1/collections/{uuid}", ""}
31         EndpointCollectionList                = APIEndpoint{"GET", "arvados/v1/collections", ""}
32         EndpointCollectionProvenance          = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/provenance", ""}
33         EndpointCollectionUsedBy              = APIEndpoint{"GET", "arvados/v1/collections/{uuid}/used_by", ""}
34         EndpointCollectionDelete              = APIEndpoint{"DELETE", "arvados/v1/collections/{uuid}", ""}
35         EndpointCollectionTrash               = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/trash", ""}
36         EndpointCollectionUntrash             = APIEndpoint{"POST", "arvados/v1/collections/{uuid}/untrash", ""}
37         EndpointSpecimenCreate                = APIEndpoint{"POST", "arvados/v1/specimens", "specimen"}
38         EndpointSpecimenUpdate                = APIEndpoint{"PATCH", "arvados/v1/specimens/{uuid}", "specimen"}
39         EndpointSpecimenGet                   = APIEndpoint{"GET", "arvados/v1/specimens/{uuid}", ""}
40         EndpointSpecimenList                  = APIEndpoint{"GET", "arvados/v1/specimens", ""}
41         EndpointSpecimenDelete                = APIEndpoint{"DELETE", "arvados/v1/specimens/{uuid}", ""}
42         EndpointContainerCreate               = APIEndpoint{"POST", "arvados/v1/containers", "container"}
43         EndpointContainerUpdate               = APIEndpoint{"PATCH", "arvados/v1/containers/{uuid}", "container"}
44         EndpointContainerGet                  = APIEndpoint{"GET", "arvados/v1/containers/{uuid}", ""}
45         EndpointContainerList                 = APIEndpoint{"GET", "arvados/v1/containers", ""}
46         EndpointContainerDelete               = APIEndpoint{"DELETE", "arvados/v1/containers/{uuid}", ""}
47         EndpointContainerLock                 = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/lock", ""}
48         EndpointContainerUnlock               = APIEndpoint{"POST", "arvados/v1/containers/{uuid}/unlock", ""}
49         EndpointContainerSSH                  = APIEndpoint{"GET", "arvados/v1/connect/{uuid}/ssh", ""} // move to /containers after #17014 fixes routing
50         EndpointContainerRequestCreate        = APIEndpoint{"POST", "arvados/v1/container_requests", "container_request"}
51         EndpointContainerRequestUpdate        = APIEndpoint{"PATCH", "arvados/v1/container_requests/{uuid}", "container_request"}
52         EndpointContainerRequestGet           = APIEndpoint{"GET", "arvados/v1/container_requests/{uuid}", ""}
53         EndpointContainerRequestList          = APIEndpoint{"GET", "arvados/v1/container_requests", ""}
54         EndpointContainerRequestDelete        = APIEndpoint{"DELETE", "arvados/v1/container_requests/{uuid}", ""}
55         EndpointGroupCreate                   = APIEndpoint{"POST", "arvados/v1/groups", "group"}
56         EndpointGroupUpdate                   = APIEndpoint{"PATCH", "arvados/v1/groups/{uuid}", "group"}
57         EndpointGroupGet                      = APIEndpoint{"GET", "arvados/v1/groups/{uuid}", ""}
58         EndpointGroupList                     = APIEndpoint{"GET", "arvados/v1/groups", ""}
59         EndpointGroupContents                 = APIEndpoint{"GET", "arvados/v1/groups/contents", ""}
60         EndpointGroupContentsUUIDInPath       = APIEndpoint{"GET", "arvados/v1/groups/{uuid}/contents", ""} // Alternative HTTP route; client-side code should always use EndpointGroupContents instead
61         EndpointGroupShared                   = APIEndpoint{"GET", "arvados/v1/groups/shared", ""}
62         EndpointGroupDelete                   = APIEndpoint{"DELETE", "arvados/v1/groups/{uuid}", ""}
63         EndpointGroupTrash                    = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/trash", ""}
64         EndpointGroupUntrash                  = APIEndpoint{"POST", "arvados/v1/groups/{uuid}/untrash", ""}
65         EndpointUserActivate                  = APIEndpoint{"POST", "arvados/v1/users/{uuid}/activate", ""}
66         EndpointUserCreate                    = APIEndpoint{"POST", "arvados/v1/users", "user"}
67         EndpointUserCurrent                   = APIEndpoint{"GET", "arvados/v1/users/current", ""}
68         EndpointUserDelete                    = APIEndpoint{"DELETE", "arvados/v1/users/{uuid}", ""}
69         EndpointUserGet                       = APIEndpoint{"GET", "arvados/v1/users/{uuid}", ""}
70         EndpointUserGetCurrent                = APIEndpoint{"GET", "arvados/v1/users/current", ""}
71         EndpointUserGetSystem                 = APIEndpoint{"GET", "arvados/v1/users/system", ""}
72         EndpointUserList                      = APIEndpoint{"GET", "arvados/v1/users", ""}
73         EndpointUserMerge                     = APIEndpoint{"POST", "arvados/v1/users/merge", ""}
74         EndpointUserSetup                     = APIEndpoint{"POST", "arvados/v1/users/setup", "user"}
75         EndpointUserSystem                    = APIEndpoint{"GET", "arvados/v1/users/system", ""}
76         EndpointUserUnsetup                   = APIEndpoint{"POST", "arvados/v1/users/{uuid}/unsetup", ""}
77         EndpointUserUpdate                    = APIEndpoint{"PATCH", "arvados/v1/users/{uuid}", "user"}
78         EndpointUserUpdateUUID                = APIEndpoint{"POST", "arvados/v1/users/{uuid}/update_uuid", ""}
79         EndpointUserBatchUpdate               = APIEndpoint{"PATCH", "arvados/v1/users/batch_update", ""}
80         EndpointUserAuthenticate              = APIEndpoint{"POST", "arvados/v1/users/authenticate", ""}
81         EndpointAPIClientAuthorizationCurrent = APIEndpoint{"GET", "arvados/v1/api_client_authorizations/current", ""}
82 )
83
84 type ContainerSSHOptions struct {
85         UUID          string `json:"uuid"`
86         DetachKeys    string `json:"detach_keys"`
87         LoginUsername string `json:"login_username"`
88 }
89
90 type ContainerSSHConnection struct {
91         Conn   net.Conn           `json:"-"`
92         Bufrw  *bufio.ReadWriter  `json:"-"`
93         Logger logrus.FieldLogger `json:"-"`
94 }
95
96 type GetOptions struct {
97         UUID         string   `json:"uuid,omitempty"`
98         Select       []string `json:"select"`
99         IncludeTrash bool     `json:"include_trash"`
100         ForwardedFor string   `json:"forwarded_for,omitempty"`
101         Remote       string   `json:"remote,omitempty"`
102 }
103
104 type UntrashOptions struct {
105         UUID             string `json:"uuid"`
106         EnsureUniqueName bool   `json:"ensure_unique_name"`
107 }
108
109 type ListOptions struct {
110         ClusterID          string                 `json:"cluster_id"`
111         Select             []string               `json:"select"`
112         Filters            []Filter               `json:"filters"`
113         Where              map[string]interface{} `json:"where"`
114         Limit              int64                  `json:"limit"`
115         Offset             int64                  `json:"offset"`
116         Order              []string               `json:"order"`
117         Distinct           bool                   `json:"distinct"`
118         Count              string                 `json:"count"`
119         IncludeTrash       bool                   `json:"include_trash"`
120         IncludeOldVersions bool                   `json:"include_old_versions"`
121         BypassFederation   bool                   `json:"bypass_federation"`
122         ForwardedFor       string                 `json:"forwarded_for,omitempty"`
123         Include            string                 `json:"include"`
124 }
125
126 type CreateOptions struct {
127         ClusterID        string                 `json:"cluster_id"`
128         EnsureUniqueName bool                   `json:"ensure_unique_name"`
129         Select           []string               `json:"select"`
130         Attrs            map[string]interface{} `json:"attrs"`
131 }
132
133 type UpdateOptions struct {
134         UUID             string                 `json:"uuid"`
135         Attrs            map[string]interface{} `json:"attrs"`
136         Select           []string               `json:"select"`
137         BypassFederation bool                   `json:"bypass_federation"`
138 }
139
140 type GroupContentsOptions struct {
141         ClusterID          string   `json:"cluster_id"`
142         UUID               string   `json:"uuid,omitempty"`
143         Select             []string `json:"select"`
144         Filters            []Filter `json:"filters"`
145         Limit              int64    `json:"limit"`
146         Offset             int64    `json:"offset"`
147         Order              []string `json:"order"`
148         Distinct           bool     `json:"distinct"`
149         Count              string   `json:"count"`
150         Include            string   `json:"include"`
151         Recursive          bool     `json:"recursive"`
152         IncludeTrash       bool     `json:"include_trash"`
153         IncludeOldVersions bool     `json:"include_old_versions"`
154         ExcludeHomeProject bool     `json:"exclude_home_project"`
155 }
156
157 type UpdateUUIDOptions struct {
158         UUID    string `json:"uuid"`
159         NewUUID string `json:"new_uuid"`
160 }
161
162 type UserActivateOptions struct {
163         UUID string `json:"uuid"`
164 }
165
166 type UserSetupOptions struct {
167         UUID                  string                 `json:"uuid,omitempty"`
168         Email                 string                 `json:"email,omitempty"`
169         OpenIDPrefix          string                 `json:"openid_prefix,omitempty"`
170         RepoName              string                 `json:"repo_name,omitempty"`
171         VMUUID                string                 `json:"vm_uuid,omitempty"`
172         SendNotificationEmail bool                   `json:"send_notification_email,omitempty"`
173         Attrs                 map[string]interface{} `json:"attrs"`
174 }
175
176 type UserMergeOptions struct {
177         NewUserUUID       string `json:"new_user_uuid,omitempty"`
178         OldUserUUID       string `json:"old_user_uuid,omitempty"`
179         NewOwnerUUID      string `json:"new_owner_uuid,omitempty"`
180         NewUserToken      string `json:"new_user_token,omitempty"`
181         RedirectToNewUser bool   `json:"redirect_to_new_user"`
182 }
183
184 type UserBatchUpdateOptions struct {
185         Updates map[string]map[string]interface{} `json:"updates"`
186 }
187
188 type UserBatchUpdateResponse struct{}
189
190 type DeleteOptions struct {
191         UUID string `json:"uuid"`
192 }
193
194 type LoginOptions struct {
195         ReturnTo string `json:"return_to"`        // On success, redirect to this target with api_token=xxx query param
196         Remote   string `json:"remote,omitempty"` // Salt token for remote Cluster ID
197         Code     string `json:"code,omitempty"`   // OAuth2 callback code
198         State    string `json:"state,omitempty"`  // OAuth2 callback state
199 }
200
201 type UserAuthenticateOptions struct {
202         Username string `json:"username,omitempty"` // PAM username
203         Password string `json:"password,omitempty"` // PAM password
204 }
205
206 type LogoutOptions struct {
207         ReturnTo string `json:"return_to"` // Redirect to this URL after logging out
208 }
209
210 type BlockWriteOptions struct {
211         Hash           string
212         Data           []byte
213         Reader         io.Reader
214         DataSize       int // Must be set if Data is nil.
215         RequestID      string
216         StorageClasses []string
217         Replicas       int
218         Attempts       int
219 }
220
221 type BlockWriteResponse struct {
222         Locator  string
223         Replicas int
224 }
225
226 type API interface {
227         ConfigGet(ctx context.Context) (json.RawMessage, error)
228         Login(ctx context.Context, options LoginOptions) (LoginResponse, error)
229         Logout(ctx context.Context, options LogoutOptions) (LogoutResponse, error)
230         CollectionCreate(ctx context.Context, options CreateOptions) (Collection, error)
231         CollectionUpdate(ctx context.Context, options UpdateOptions) (Collection, error)
232         CollectionGet(ctx context.Context, options GetOptions) (Collection, error)
233         CollectionList(ctx context.Context, options ListOptions) (CollectionList, error)
234         CollectionProvenance(ctx context.Context, options GetOptions) (map[string]interface{}, error)
235         CollectionUsedBy(ctx context.Context, options GetOptions) (map[string]interface{}, error)
236         CollectionDelete(ctx context.Context, options DeleteOptions) (Collection, error)
237         CollectionTrash(ctx context.Context, options DeleteOptions) (Collection, error)
238         CollectionUntrash(ctx context.Context, options UntrashOptions) (Collection, error)
239         ContainerCreate(ctx context.Context, options CreateOptions) (Container, error)
240         ContainerUpdate(ctx context.Context, options UpdateOptions) (Container, error)
241         ContainerGet(ctx context.Context, options GetOptions) (Container, error)
242         ContainerList(ctx context.Context, options ListOptions) (ContainerList, error)
243         ContainerDelete(ctx context.Context, options DeleteOptions) (Container, error)
244         ContainerLock(ctx context.Context, options GetOptions) (Container, error)
245         ContainerUnlock(ctx context.Context, options GetOptions) (Container, error)
246         ContainerSSH(ctx context.Context, options ContainerSSHOptions) (ContainerSSHConnection, error)
247         ContainerRequestCreate(ctx context.Context, options CreateOptions) (ContainerRequest, error)
248         ContainerRequestUpdate(ctx context.Context, options UpdateOptions) (ContainerRequest, error)
249         ContainerRequestGet(ctx context.Context, options GetOptions) (ContainerRequest, error)
250         ContainerRequestList(ctx context.Context, options ListOptions) (ContainerRequestList, error)
251         ContainerRequestDelete(ctx context.Context, options DeleteOptions) (ContainerRequest, error)
252         GroupCreate(ctx context.Context, options CreateOptions) (Group, error)
253         GroupUpdate(ctx context.Context, options UpdateOptions) (Group, error)
254         GroupGet(ctx context.Context, options GetOptions) (Group, error)
255         GroupList(ctx context.Context, options ListOptions) (GroupList, error)
256         GroupContents(ctx context.Context, options GroupContentsOptions) (ObjectList, error)
257         GroupShared(ctx context.Context, options ListOptions) (GroupList, error)
258         GroupDelete(ctx context.Context, options DeleteOptions) (Group, error)
259         GroupTrash(ctx context.Context, options DeleteOptions) (Group, error)
260         GroupUntrash(ctx context.Context, options UntrashOptions) (Group, error)
261         SpecimenCreate(ctx context.Context, options CreateOptions) (Specimen, error)
262         SpecimenUpdate(ctx context.Context, options UpdateOptions) (Specimen, error)
263         SpecimenGet(ctx context.Context, options GetOptions) (Specimen, error)
264         SpecimenList(ctx context.Context, options ListOptions) (SpecimenList, error)
265         SpecimenDelete(ctx context.Context, options DeleteOptions) (Specimen, error)
266         UserCreate(ctx context.Context, options CreateOptions) (User, error)
267         UserUpdate(ctx context.Context, options UpdateOptions) (User, error)
268         UserUpdateUUID(ctx context.Context, options UpdateUUIDOptions) (User, error)
269         UserMerge(ctx context.Context, options UserMergeOptions) (User, error)
270         UserActivate(ctx context.Context, options UserActivateOptions) (User, error)
271         UserSetup(ctx context.Context, options UserSetupOptions) (map[string]interface{}, error)
272         UserUnsetup(ctx context.Context, options GetOptions) (User, error)
273         UserGet(ctx context.Context, options GetOptions) (User, error)
274         UserGetCurrent(ctx context.Context, options GetOptions) (User, error)
275         UserGetSystem(ctx context.Context, options GetOptions) (User, error)
276         UserList(ctx context.Context, options ListOptions) (UserList, error)
277         UserDelete(ctx context.Context, options DeleteOptions) (User, error)
278         UserBatchUpdate(context.Context, UserBatchUpdateOptions) (UserList, error)
279         UserAuthenticate(ctx context.Context, options UserAuthenticateOptions) (APIClientAuthorization, error)
280         APIClientAuthorizationCurrent(ctx context.Context, options GetOptions) (APIClientAuthorization, error)
281 }