Documentation
¶
Overview ¶
Package resourceupload is the single-use upload link (#2639): manage_resource action=upload_link issues a short-lived URL on the platform's own public origin, and one PUT of a file to it from the agent's shell files the file as a managed resource at the address the link was issued for, as the person who asked for it, with the checks a portal upload gets. The bytes never pass through a tool call, and nothing about object storage has to be public.
The link's token is a bearer credential for one write. It is handed to the caller once and never stored: a link is found by the token's SHA-256, claimed by one atomic statement that also refuses a used or expired link, and bound to its address, its declared type and its size.
Index ¶
Constants ¶
const ( DefaultTTL = 15 * time.Minute MaxTTL = time.Hour )
How long a link lives: DefaultTTL unless the caller asks for less, never more than MaxTTL.
const Route = "PUT " + RoutePrefix + "{token}"
Route is the pattern a link is PUT to.
const RoutePrefix = "/api/v1/resources/uploads/"
RoutePrefix is where a link is PUT to, followed by its token.
Variables ¶
var ( // ErrNoLink is a token no link answers to: unknown, used or expired, // which are told apart to no one. ErrNoLink = errors.New("this upload link is unknown, used or expired: ask for a new one with manage_resource action=upload_link") // ErrTooLarge is a file past the size the link was issued for. ErrTooLarge = errors.New("the file is larger than the size this upload link was issued for") // ErrRefused is a link that cannot be issued as asked. ErrRefused = errors.New("refused") )
Errors the HTTP surface answers by identity.
Functions ¶
Types ¶
type IssueRequest ¶
type IssueRequest struct {
Scope resource.Scope
ScopeID string
Path string
Filename string
DisplayName string
Description string
Tags []string
ContentType string
IfExists string
// MaxBytes is the most the file may be.
MaxBytes int64
// TTL is how long the link lives; zero is DefaultTTL.
TTL time.Duration
}
IssueRequest is a link as the caller asks for it, its address already resolved and checked by manage_resource.
type Issued ¶
type Issued struct {
URL string `json:"upload_url"`
Method string `json:"method"`
ExpiresAt time.Time `json:"expires_at"`
MaxBytes int64 `json:"max_bytes"`
}
Issued is a link as the caller is handed it, once.
type PostgresStore ¶
PostgresStore keeps the links in resource_upload_links.
func NewStore ¶
func NewStore(db *sql.DB) *PostgresStore
NewStore is the links' store over db, nil without one.
type Service ¶
type Service struct {
Store Store
Writer Writer
// BaseURL is the platform's public origin (portal.public_base_url); a
// link is not issued without one, since there is nothing to name.
BaseURL func() string
// MaxUploadBytes is the deployment's upload ceiling; non-positive is
// resource.MaxUploadBytes.
MaxUploadBytes int64
// Now is the clock; nil is time.Now.
Now func() time.Time
}
Service issues links and files what is PUT to them.
func (*Service) Issue ¶
func (s *Service) Issue(ctx context.Context, in IssueRequest, claims resource.Claims, userID string) (Issued, error)
Issue keeps a link for in, writable by claims, and returns it.
func (*Service) Mount ¶
Mount registers the link's route on mux. The route takes no session or key: the link is the credential.
func (*Service) Upload ¶
func (s *Service) Upload(ctx context.Context, token string, body io.Reader, declared int64) (*resource.Resource, error)
Upload files body, PUT to the link token names, at the link's address as the person who asked for it. declared is the request's Content-Length, -1 when it sent none. The link is spent whatever the outcome.
type Store ¶
type Store interface {
// contains filtered or unexported methods
}
Store keeps the links (PostgresStore).
type Writer ¶
type Writer interface {
Create(ctx context.Context, in resource.NewResource, claims resource.Claims) (*resource.Resource, error)
Replace(ctx context.Context, id string, up resource.RevisionUpload, claims resource.Claims) (*resource.Resource, int, error)
Locate(ctx context.Context, addr toolkit.ResourceAddress, claims resource.Claims) (*resource.Resource, string, error)
}
Writer is what files the upload: the writer behind manage_resource.