3f38a7ed1e
Moving lib/uplink actually makes implementing the new library harder. Move the package back where it was. Change-Id: If758e897e3e56155a48ae82b23904cd8cdd72c13
121 lines
4.0 KiB
Go
121 lines
4.0 KiB
Go
// Copyright (C) 2019 Storj Labs, Inc.
|
|
// See LICENSE for copying information.
|
|
|
|
/*
|
|
Package uplink is the main entrypoint to interacting with Storj Labs' decentralized
|
|
storage network.
|
|
|
|
Projects
|
|
|
|
An (*Uplink) reference lets you open a *Project, which should have already been created via
|
|
the web interface of one of the Storj Labs or Tardigrade network Satellites. You may be able
|
|
to create or access your us-central-1 account here: https://us-central-1.tardigrade.io/
|
|
|
|
Opening a *Project requires a specific Satellite address (e.g. "us-central-1.tardigrade.io:7777")
|
|
and an API key. The API key will grant specific access to certain operations and resources within
|
|
a project. Projects allow you to manage and open Buckets.
|
|
|
|
Example:
|
|
|
|
ul, err := uplink.NewUplink(ctx, nil)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer ul.Close()
|
|
|
|
p, err := ul.OpenProject(ctx, "us-central-1.tardigrade.io:7777", apiKey)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer p.Close()
|
|
|
|
API Keys
|
|
|
|
An API key is a "macaroon" (see https://ai.google/research/pubs/pub41892). As such, API keys
|
|
can be restricted such that users of the restricted API key only have access to a subset of
|
|
what the parent API key allowed. It is possible to restrict a macaroon to specific operations,
|
|
buckets, paths, path prefixes, or time windows.
|
|
|
|
If you need a valid API key, please visit your chosen Satellite's web interface.
|
|
|
|
Example:
|
|
|
|
adminKey, err := uplink.ParseAPIKey("13YqeJ3Xk4KHocypZMdQZZqfC1goMvxbYSCWWEjSmew6rVvJp3GCK")
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
|
|
readOnlyKey, err := adminKey.Restrict(macaroon.Caveat{
|
|
DisallowWrites: true,
|
|
DisallowLists: true,
|
|
DisallowDeletes: true,
|
|
})
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
|
|
// return a new restricted key that is read only
|
|
return readOnlyKey.Serialize()
|
|
|
|
Restricting an API key to a path prefix is most easily accomplished using an
|
|
EncryptionAccess, so see EncryptionAccess for more.
|
|
|
|
Buckets
|
|
|
|
A bucket represents a collection of objects. You can upload, download, list, and delete objects of
|
|
any size or shape. Objects within buckets are represented by keys, where keys can optionally be
|
|
listed using the "/" delimiter. Objects are always end-to-end encrypted.
|
|
|
|
b, err := p.OpenBucket(ctx, "staging", access)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer b.Close()
|
|
|
|
EncryptionAccess
|
|
|
|
Where an APIKey controls what resources and operations a Satellite will allow a user to access
|
|
and perform, an EncryptionAccess controls what buckets, path prefixes, and objects a user has the
|
|
ability to decrypt. An EncryptionAccess is a serializable collection of hierarchically-determined
|
|
encryption keys, where by default the key starts at the root.
|
|
|
|
As an example, the following code creates an encryption access context (and API key) that is
|
|
restricted to objects with the prefix "/logs/" inside the staging bucket.
|
|
|
|
access := uplink.NewEncryptionAccessWithDefaultKey(defaultKey)
|
|
logServerKey, logServerAccess, err := access.Restrict(
|
|
readOnlyKey, uplink.EncryptionRestriction{
|
|
Bucket: "staging",
|
|
Path: "/logs/",
|
|
})
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
return logServerAccess.Serialize()
|
|
|
|
The keys to decrypt data in other buckets or in other path prefixes are not contained in this
|
|
new serialized encryption access context. This new encryption access context only provides the
|
|
information for just what is necessary.
|
|
|
|
Objects
|
|
|
|
Objects support a couple kilobytes of arbitrary key/value metadata, an arbitrary-size primary
|
|
data streams, with seeking. If you want to access only a small subrange of the data you
|
|
uploaded, you can download only the range of the data you need in a fast and performant way.
|
|
This allows you to stream video straight out of the network with little overhead.
|
|
|
|
obj, err := b.OpenObject(ctx, "/logs/webserver.log")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer obj.Close()
|
|
|
|
reader, err := obj.DownloadRange(ctx, 0, -1)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer reader.Close()
|
|
|
|
*/
|
|
package uplink
|