1 /* Provides low-level Get/Put primitives for accessing Arvados Keep blocks. */
20 // A Keep "block" is 64MB.
21 const BLOCKSIZE = 64 * 1024 * 1024
23 var BlockNotFound = errors.New("Block not found")
24 var InsufficientReplicasError = errors.New("Could not write sufficient replicas")
25 var OversizeBlockError = errors.New("Block too big")
26 var MissingArvadosApiHost = errors.New("Missing required environment variable ARVADOS_API_HOST")
27 var MissingArvadosApiToken = errors.New("Missing required environment variable ARVADOS_API_TOKEN")
29 const X_Keep_Desired_Replicas = "X-Keep-Desired-Replicas"
30 const X_Keep_Replicas_Stored = "X-Keep-Replicas-Stored"
32 // Information about Arvados and Keep servers.
33 type KeepClient struct {
41 service_roots *[]string
45 // Create a new KeepClient, initialized with standard Arvados environment
46 // variables ARVADOS_API_HOST, ARVADOS_API_TOKEN, and (optionally)
47 // ARVADOS_API_HOST_INSECURE. This will contact the API server to discover
49 func MakeKeepClient() (kc KeepClient, err error) {
50 insecure := (os.Getenv("ARVADOS_API_HOST_INSECURE") == "true")
51 external := (os.Getenv("ARVADOS_EXTERNAL_CLIENT") == "true")
54 ApiServer: os.Getenv("ARVADOS_API_HOST"),
55 ApiToken: os.Getenv("ARVADOS_API_TOKEN"),
56 ApiInsecure: insecure,
58 Client: &http.Client{Transport: &http.Transport{
59 TLSClientConfig: &tls.Config{InsecureSkipVerify: insecure}}},
63 if os.Getenv("ARVADOS_API_HOST") == "" {
64 return kc, MissingArvadosApiHost
66 if os.Getenv("ARVADOS_API_TOKEN") == "" {
67 return kc, MissingArvadosApiToken
70 err = (&kc).DiscoverKeepServers()
75 // Put a block given the block hash, a reader with the block data, and the
76 // expected length of that data. The desired number of replicas is given in
77 // KeepClient.Want_replicas. Returns the number of replicas that were written
78 // and if there was an error. Note this will return InsufficientReplias
79 // whenever 0 <= replicas < this.Wants_replicas.
80 func (this KeepClient) PutHR(hash string, r io.Reader, expectedLength int64) (replicas int, err error) {
82 // Buffer for reads from 'r'
84 if expectedLength > 0 {
85 if expectedLength > BLOCKSIZE {
86 return 0, OversizeBlockError
88 bufsize = int(expectedLength)
93 t := streamer.AsyncStreamFromReader(bufsize, HashCheckingReader{r, md5.New(), hash})
96 return this.putReplicas(hash, t, expectedLength)
99 // Put a block given the block hash and a byte buffer. The desired number of
100 // replicas is given in KeepClient.Want_replicas. Returns the number of
101 // replicas that were written and if there was an error. Note this will return
102 // InsufficientReplias whenever 0 <= replicas < this.Wants_replicas.
103 func (this KeepClient) PutHB(hash string, buf []byte) (replicas int, err error) {
104 t := streamer.AsyncStreamFromSlice(buf)
107 return this.putReplicas(hash, t, int64(len(buf)))
110 // Put a block given a buffer. The hash will be computed. The desired number
111 // of replicas is given in KeepClient.Want_replicas. Returns the number of
112 // replicas that were written and if there was an error. Note this will return
113 // InsufficientReplias whenever 0 <= replicas < this.Wants_replicas.
114 func (this KeepClient) PutB(buffer []byte) (hash string, replicas int, err error) {
115 hash = fmt.Sprintf("%x", md5.Sum(buffer))
116 replicas, err = this.PutHB(hash, buffer)
117 return hash, replicas, err
120 // Put a block, given a Reader. This will read the entire reader into a buffer
121 // to computed the hash. The desired number of replicas is given in
122 // KeepClient.Want_replicas. Returns the number of replicas that were written
123 // and if there was an error. Note this will return InsufficientReplias
124 // whenever 0 <= replicas < this.Wants_replicas. Also nhote that if the block
125 // hash and data size are available, PutHR() is more efficient.
126 func (this KeepClient) PutR(r io.Reader) (hash string, replicas int, err error) {
127 if buffer, err := ioutil.ReadAll(r); err != nil {
130 return this.PutB(buffer)
134 // Get a block given a hash. Return a reader, the expected data length, the
135 // URL the block was fetched from, and if there was an error. If the block
136 // checksum does not match, the final Read() on the reader returned by this
137 // method will return a BadChecksum error instead of EOF.
138 func (this KeepClient) Get(hash string) (reader io.ReadCloser,
139 contentLength int64, url string, err error) {
140 return this.AuthorizedGet(hash, "", "")
143 // Get a block given a hash, with additional authorization provided by
144 // signature and timestamp. Return a reader, the expected data length, the URL
145 // the block was fetched from, and if there was an error. If the block
146 // checksum does not match, the final Read() on the reader returned by this
147 // method will return a BadChecksum error instead of EOF.
148 func (this KeepClient) AuthorizedGet(hash string,
150 timestamp string) (reader io.ReadCloser,
151 contentLength int64, url string, err error) {
153 // Calculate the ordering for asking servers
154 sv := this.shuffledServiceRoots(hash)
156 for _, host := range sv {
157 var req *http.Request
161 url = fmt.Sprintf("%s/%s+A%s@%s", host, hash,
162 signature, timestamp)
164 url = fmt.Sprintf("%s/%s", host, hash)
166 if req, err = http.NewRequest("GET", url, nil); err != nil {
170 req.Header.Add("Authorization", fmt.Sprintf("OAuth2 %s", this.ApiToken))
172 var resp *http.Response
173 if resp, err = this.Client.Do(req); err != nil {
177 if resp.StatusCode == http.StatusOK {
178 return HashCheckingReader{resp.Body, md5.New(), hash}, resp.ContentLength, url, nil
182 return nil, 0, "", BlockNotFound
185 // Determine if a block with the given hash is available and readable, but does
186 // not return the block contents.
187 func (this KeepClient) Ask(hash string) (contentLength int64, url string, err error) {
188 return this.AuthorizedAsk(hash, "", "")
191 // Determine if a block with the given hash is available and readable with the
192 // given signature and timestamp, but does not return the block contents.
193 func (this KeepClient) AuthorizedAsk(hash string, signature string,
194 timestamp string) (contentLength int64, url string, err error) {
195 // Calculate the ordering for asking servers
196 sv := this.shuffledServiceRoots(hash)
198 for _, host := range sv {
199 var req *http.Request
202 url = fmt.Sprintf("%s/%s+A%s@%s", host, hash,
203 signature, timestamp)
205 url = fmt.Sprintf("%s/%s", host, hash)
208 if req, err = http.NewRequest("HEAD", url, nil); err != nil {
212 req.Header.Add("Authorization", fmt.Sprintf("OAuth2 %s", this.ApiToken))
214 var resp *http.Response
215 if resp, err = this.Client.Do(req); err != nil {
219 if resp.StatusCode == http.StatusOK {
220 return resp.ContentLength, url, nil
224 return 0, "", BlockNotFound
228 // Atomically read the service_roots field.
229 func (this *KeepClient) ServiceRoots() []string {
230 r := (*[]string)(atomic.LoadPointer((*unsafe.Pointer)(unsafe.Pointer(&this.service_roots))))
234 // Atomically update the service_roots field. Enables you to update
235 // service_roots without disrupting any GET or PUT operations that might
236 // already be in progress.
237 func (this *KeepClient) SetServiceRoots(svc []string) {
238 // Must be sorted for ShuffledServiceRoots() to produce consistent
240 roots := make([]string, len(svc))
243 atomic.StorePointer((*unsafe.Pointer)(unsafe.Pointer(&this.service_roots)),
244 unsafe.Pointer(&roots))