contribution

package module
v0.0.0-...-822b6ff Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

README

StuHelper Storage Contribution

独立存储贡献库，管理同意、容量、期限、暂停、退出和迁移观测。通过 storage 公共接口协作，不保存供应商凭据，不读写业务或账务数据。

运行要求为 Go 1.27.3、Node.js 24.22.1、pnpm 10.33.4 和隔离 PostgreSQL 18。使用 make setup 安装锁定工具，bash scripts/check-with-postgres.sh 启动临时数据库并执行全部检查。

OpenAPI 位于 contracts，make generate 生成 SDK。独立应用装配提供运行身份、条款、容量及期限配置、当前授权检查，并持续执行有界 Sweep 与 RunOne。代码本身不会登录供应商或启动后台进程。

行为及剩余范围见 贡献规格。许可为 AGPL-3.0-only。

Documentation

Overview

Package contribution manages voluntary storage consent without holding provider credentials.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInput       = errors.New("contribution_invalid_input")
	ErrDenied      = errors.New("contribution_permission_denied")
	ErrNotFound    = errors.New("contribution_not_found")
	ErrConflict    = errors.New("contribution_conflict")
	ErrUnavailable = errors.New("contribution_unavailable")
)

Functions

func OwnerDomain 

func OwnerDomain(p Principal) string

OwnerDomain is the stable storage ownership binding, including identity issuer.

Types

type Access 

type Access struct {
	ID    string
	Owner Principal
}

type Authorizer 

type Authorizer interface {
	Authorize(context.Context, Principal, string, Access) error
}

type CommandRequest 

type CommandRequest struct {
	Revision   int64       `json:"revision"`
	Action     string      `json:"action"`
	Conditions *Conditions `json:"conditions,omitempty"`
	Consent    *Consent    `json:"consent,omitempty"`
}

type Conditions 

type Conditions struct {
	LimitBytes      int64     `json:"limit_bytes"`
	PersonalReserve int64     `json:"personal_reserve"`
	Until           time.Time `json:"until"`
}

type Config 

type Config struct {
	Policy           Policy
	Actor            Principal
	Clock            func() time.Time
	OperationTimeout time.Duration
	RefreshInterval  time.Duration
	Lease            time.Duration
	MaxAttempts      int
	MaxContributions int
}
type Consent struct {
	Accepted bool   `json:"accepted"`
	Version  string `json:"version"`
	Digest   string `json:"digest"`
}

type CreateRequest 

type CreateRequest struct {
	InstanceID string     `json:"instance_id"`
	Conditions Conditions `json:"conditions"`
	Consent    Consent    `json:"consent"`
}

type Event 

type Event struct {
	SpecVersion     string    `json:"specversion"`
	Source          string    `json:"source"`
	ID              string    `json:"id"`
	Type            string    `json:"type"`
	Subject         string    `json:"subject"`
	Time            time.Time `json:"time"`
	DataContentType string    `json:"datacontenttype"`
	Data            EventData `json:"data"`
	Actor           Principal `json:"-"`
}

type EventData 

type EventData struct {
	Revision        int64  `json:"revision"`
	DesiredRevision int64  `json:"desired_revision"`
	AppliedRevision int64  `json:"applied_revision"`
	State           string `json:"state"`
}

type Job 

type Job struct {
	ID          string
	State       string
	Generation  int64
	LeaseOwner  string
	LeaseUntil  time.Time
	AvailableAt time.Time
	Attempts    int
}

type Observation 

type Observation struct {
	ObservedAt             time.Time `json:"observed_at"`
	AuthorizationExpiresAt time.Time `json:"authorization_expires_at"`
	QuotaExpiresAt         time.Time `json:"quota_expires_at"`
	Authorized             bool      `json:"authorized"`
	UsedBytes              int64     `json:"used_bytes"`
	ReservedBytes          int64     `json:"reserved_bytes"`
	AvailableBytes         int64     `json:"available_bytes"`
	RemainingReplicas      int64     `json:"remaining_replicas"`
}

type Page 

type Page struct {
	Items      []View `json:"items"`
	NextCursor string `json:"next_cursor"`
}

type Policy 

type Policy struct {
	Terms                    Terms    `json:"terms"`
	Adapters                 []string `json:"adapters"`
	MinBytes                 int64    `json:"min_bytes"`
	MaxBytes                 int64    `json:"max_bytes"`
	MinTermSeconds           int64    `json:"min_term_seconds"`
	MaxTermSeconds           int64    `json:"max_term_seconds"`
	ExitTargetSeconds        int64    `json:"exit_target_seconds"`
	MaxPerOwner              int      `json:"max_per_owner"`
	ObservationMaxAgeSeconds int64    `json:"observation_max_age_seconds"`
}

type Principal 

type Principal = storage.Principal

type Record 

type Record struct {
	View          View
	Owner         Principal
	InstanceID    string
	EventRevision int64
}

Record and Job belong to this module's repository; they are never HTTP responses.

type Replay 

type Replay struct {
	Key, Hash string
	Result    View
	ExpiresAt time.Time
}

type Repository 

type Repository interface {
	Transaction(context.Context, func(Transaction) error) error
	Claim(context.Context, string, time.Time, time.Duration) (Job, error)
	PendingEvents(context.Context, int) ([]Event, error)
	AcknowledgeEvent(context.Context, string) error
}

type RetryRequest 

type RetryRequest struct {
	Revision int64 `json:"revision"`
}

type Service 

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

func New 

func New(r Repository, a Authorizer, st Store, c Config) (*Service, error)

func (*Service) Command 

func (s *Service) Command(ctx context.Context, p Principal, id, key string, q CommandRequest) (View, error)

func (*Service) Create 

func (s *Service) Create(ctx context.Context, p Principal, key string, q CreateRequest) (View, error)

func (*Service) Get 

func (s *Service) Get(ctx context.Context, p Principal, id string) (View, error)

func (*Service) List 

func (s *Service) List(ctx context.Context, p Principal, n int, after string) (Page, error)

func (*Service) Operations 

func (s *Service) Operations(ctx context.Context, p Principal, n int, after string) (Page, error)

func (*Service) Options 

func (s *Service) Options(ctx context.Context, p Principal, n int, after string) (storage.ContributionCandidates, error)

Options derives ownership from the verified principal, never a query field.

func (*Service) Policy 

func (s *Service) Policy() Policy

func (*Service) RetryOperation 

func (s *Service) RetryOperation(ctx context.Context, p Principal, id, key string, q RetryRequest) (View, error)

func (*Service) RunOne 

func (s *Service) RunOne(ctx context.Context, worker string) error

func (*Service) Statistics 

func (s *Service) Statistics(ctx context.Context) (Statistics, error)

func (*Service) Sweep 

func (s *Service) Sweep(ctx context.Context, n int, after string) (string, error)

Sweep converts expired consent into a durable exit request, including blocked activation jobs. Storage independently stops writes at the consent deadline.

type Statistics 

type Statistics struct {
	DeclaredBytes     int64     `json:"declared_bytes"`
	AvailableBytes    int64     `json:"available_bytes"`
	UsedBytes         int64     `json:"used_bytes"`
	ReservedBytes     int64     `json:"reserved_bytes"`
	Contributions     int       `json:"contributions"`
	FreshObservations int       `json:"fresh_observations"`
	Status            string    `json:"status"`
	GeneratedAt       time.Time `json:"generated_at"`
}

type Store 

type Store interface {
	ListContributionCandidates(context.Context, Principal, string, int, string) (storage.ContributionCandidates, error)
	InspectContribution(context.Context, Principal, string, string) (storage.ContributionSnapshot, error)
	ApplyContribution(context.Context, Principal, string, storage.ContributionControl) (storage.ContributionSnapshot, error)
}

Store exposes only the provider-independent contribution control boundary.

type Terms 

type Terms struct {
	Version string `json:"version"`
	Digest  string `json:"digest"`
	URL     string `json:"url"`
}

type Transaction 

type Transaction interface {
	Lock(string) error
	Record(string) (Record, error)
	SaveRecord(Record) error
	List(Principal, int, string) ([]Record, error)
	Scan(int, string) ([]Record, error)
	Counts(Principal) (total, owned int, err error)
	Job(string) (Job, error)
	SaveJob(Job) error
	Replay(string) (Replay, error)
	SaveReplay(Replay) error
	PruneReplays(time.Time, int) error
	Event(Event) error
}

Lock order is replay -> record -> job. Claim only locks a job, commits, then starts external work; a storage request never holds a module transaction.

type View 

type View struct {
	ID              string       `json:"id"`
	Adapter         string       `json:"adapter"`
	Revision        int64        `json:"revision"`
	AppliedRevision int64        `json:"applied_revision"`
	DesiredState    string       `json:"desired_state"`
	State           string       `json:"state"`
	Reason          string       `json:"reason"`
	Conditions      Conditions   `json:"conditions"`
	Consent         Terms        `json:"consent"`
	AcceptedAt      time.Time    `json:"accepted_at"`
	CreatedAt       time.Time    `json:"created_at"`
	UpdatedAt       time.Time    `json:"updated_at"`
	ExitRequestedAt *time.Time   `json:"exit_requested_at,omitempty"`
	ExitTargetAt    *time.Time   `json:"exit_target_at,omitempty"`
	Observation     *Observation `json:"observation,omitempty"`
}

View deliberately omits the principal, provider instance and all custody details.

Source Files

View all Source files

Directories

Path Synopsis
Package httpapi exposes user-owned contribution requests and anonymous aggregate policy.
 Package httpapi exposes user-owned contribution requests and anonymous aggregate policy.
Package postgres owns contribution metadata and its independent runtime identity.
 Package postgres owns contribution metadata and its independent runtime identity.
Package sdk provides primitives to interact with the openapi HTTP API.
 Package sdk provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.