uploadsessions

package
v0.0.0-...-3ac6500 Latest Latest
Warning

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

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

README

github.com/ubgo/filesystem/records/uploadsessions

The records-backed upload.SessionStore: upload sessions (server-issued upload tokens valid for a window, UP-15) kept in the database, so they survive a restart and are shared by every instance behind a load balancer. upload.Sessions does every check (the secret in constant time, the expiry by its own clock, the limits against the endpoint's policy); this package only keeps the rows. The guide is Upload sessions; the concept is introduced in Uploads.

Install

go get github.com/ubgo/filesystem/records

The package is in the records module, which requires only github.com/ubgo/sqlb and the core module.

Wire it

p := uploadsessions.New()
store, err := records.New(db, sqlb.PostgresDialect{}, disks, records.WithPlugins(p))
// store.Migrate(ctx) creates fs_upload_sessions.
sessions, err := upload.NewSessions(p.Store(store), upload.SessionsOptions{})
h := upload.Handler(disk, policy, upload.HandlerOptions{Resolve: sessions.Resolver()})

Schedule sessions.Sweep(ctx); an expired session is refused whether or not it was swept.

Go API

Name What it is
New() the plugin; install it with records.WithPlugins
Plugin.Store(s) the upload.SessionStore over s's database; statements join the transaction in ctx
Store.SaveSession, LoadSession, DeleteSession, SweepSessions the four upload.SessionStore methods: a duplicate ID is exists, an unknown one not_found, delete is idempotent, sweep is one DELETE of the sessions expired at now

Table

fs_upload_sessions (constant TableNameSessions), migration uploadsessions/0001_upload_sessions:

Column Constant Type Notes
id ColID key primary key, ups_…
secret_hash ColSecretHash short hex SHA-256 of the token's secret; never the secret
storage_key ColKey long the session's one key, or ""
prefix ColPrefix long the session's key prefix, or ""
max_size ColMaxSize 64-bit integer 0 keeps the policy's
allowed ColAllowed doc JSON array of type patterns; a row that does not parse is an error, never a session without type limits
created_at ColCreatedAt timestamp UTC
expires_at ColExpiresAt timestamp UTC; index fs_upload_sessions_expires for the sweep

Sessions belong to no scope, so PurgeScope leaves them; they expire within upload.MaxSessionLifetime (7 days) and the sweep deletes them.

Documentation

Overview

Package uploadsessions is a records plugin that keeps upload sessions (upload.Session, UP-15) in the database: the SessionStore to use when sessions must survive a restart or be shared by several instances behind a load balancer. upload.Sessions does every check (the secret, the expiry by its own clock, the limits against the endpoint's policy); this store only keeps the rows, never a token's secret, only its SHA-256.

p := uploadsessions.New()
store, _ := records.New(db, dialect, disks, records.WithPlugins(p))
sessions, _ := upload.NewSessions(p.Store(store), upload.SessionsOptions{})

Schedule sessions.Sweep (the library starts no background work); an expired session is refused whether or not it was swept.

Index

Constants

View Source
const (
	ColID         = "id"
	ColSecretHash = "secret_hash"
	ColKey        = "storage_key"
	ColPrefix     = "prefix"
	ColMaxSize    = "max_size"
	ColAllowed    = "allowed"
	ColCreatedAt  = "created_at"
	ColExpiresAt  = "expires_at"
)

Column names of fs_upload_sessions.

View Source
const PluginName = "uploadsessions"

PluginName is the plugin's name in the migration ledger.

View Source
const TableNameSessions = "fs_upload_sessions"

TableNameSessions is the table the plugin owns: one row per session.

Variables

View Source
var (
	Table      = sqlb.Table{Name: TableNameSessions, Alias: "us"}
	ID         = sqlb.Col[string](Table, ColID)
	SecretHash = sqlb.Col[string](Table, ColSecretHash)
	// Key and Prefix: exactly one is set ("" for the other), as in
	// upload.Session.
	Key     = sqlb.Col[string](Table, ColKey)
	Prefix  = sqlb.Col[string](Table, ColPrefix)
	MaxSize = sqlb.Col[int64](Table, ColMaxSize)
	// Allowed is the session's type patterns as a JSON array, "[]" or
	// "null" for none (the policy's types).
	Allowed   = sqlb.Col[string](Table, ColAllowed)
	CreatedAt = sqlb.Col[time.Time](Table, ColCreatedAt)
	ExpiresAt = sqlb.Col[time.Time](Table, ColExpiresAt)
)

Table and typed columns.

Functions

This section is empty.

Types

type Plugin

type Plugin struct{}

Plugin owns the sessions table. Construct it with New, install it with records.WithPlugins, and get the SessionStore with Store.

func New

func New() *Plugin

New returns a Plugin.

func (*Plugin) Migrations

func (p *Plugin) Migrations(engine string) ([]records.Migration, error)

Migrations implements records.Migrator.

func (*Plugin) Name

func (p *Plugin) Name() string

Name implements records.Plugin.

func (*Plugin) Store

func (p *Plugin) Store(s *records.Store) Store

Store returns the upload.SessionStore over s's database. The plugin must be installed in s (its table exists only then).

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is an upload.SessionStore in the records database. Statements join the transaction in ctx, if any (records.Store.Tx).

func (Store) DeleteSession

func (st Store) DeleteSession(ctx context.Context, id string) error

DeleteSession implements upload.SessionStore.

func (Store) LoadSession

func (st Store) LoadSession(ctx context.Context, id string) (upload.Session, error)

LoadSession implements upload.SessionStore: CodeNotFound when there is no session with id.

func (Store) SaveSession

func (st Store) SaveSession(ctx context.Context, sess upload.Session) error

SaveSession implements upload.SessionStore. An ID already present is CodeExists.

func (Store) SweepSessions

func (st Store) SweepSessions(ctx context.Context, now time.Time) (int, error)

SweepSessions implements upload.SessionStore: one DELETE of every session expired at now.

Jump to

Keyboard shortcuts

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