resourceupload

package
v1.163.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

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

View Source
const (
	DefaultTTL = 15 * time.Minute
	MaxTTL     = time.Hour
)

How long a link lives: DefaultTTL unless the caller asks for less, never more than MaxTTL.

View Source
const Route = "PUT " + RoutePrefix + "{token}"

Route is the pattern a link is PUT to.

View Source
const RoutePrefix = "/api/v1/resources/uploads/"

RoutePrefix is where a link is PUT to, followed by its token.

Variables

View Source
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

func Hash

func Hash(token string) string

Hash is the form a token is kept and found by.

func MountFrom

func MountFrom[T any](mux *http.ServeMux, kits []T)

MountFrom registers the link's route on mux from the toolkit among kits that issues links (the portal toolkit's MountUploadlinks).

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

type PostgresStore struct {
	DB *sql.DB
}

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

func (s *Service) Mount(mux *http.ServeMux)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL