usage

package
v0.4.5 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TransferEventAccessIssued = "access_issued"

	ProviderTransferDirectionDownload = "download"
	ProviderTransferDirectionUpload   = "upload"

	ProviderTransferMatched   = "matched"
	ProviderTransferAmbiguous = "ambiguous"
	ProviderTransferUnmatched = "unmatched"
)
View Source
const (
	DefaultTransferBreakdownPageSize = 200
	MaxTransferBreakdownPageSize     = 1000
)

Variables

View Source
var (
	ErrReportsUnavailable = fmt.Errorf("usage report store is unavailable")
	ErrObjectsUnavailable = fmt.Errorf("usage object reader is unavailable")
	ErrInvalidGroupBy     = fmt.Errorf("invalid transfer breakdown group_by")
)

Functions

func EventID

func EventID(event Event) string

func GrantID

func GrantID(event Event) string

func NormalizeProviderEvent added in v0.4.2

NormalizeProviderEvent validates and canonicalizes one provider event before it reaches a persistence writer.

func ParseInactiveSince added in v0.4.2

func ParseInactiveSince(now time.Time, inactiveDays *int) (*time.Time, error)

ParseInactiveSince computes the report cutoff from an explicit clock so the use case remains deterministic under tests and callers control UTC policy.

Types

type Dependencies

type Dependencies struct {
	Reports ReportStore
	Objects ObjectReader
}

type Event

type Event struct {
	EventID           string
	AccessGrantID     string
	EventType         string
	Direction         string
	EventTime         time.Time
	RequestID         string
	ObjectID          string
	SHA256            string
	ObjectSize        int64
	Organization      string
	Project           string
	AccessID          string
	Provider          string
	Bucket            string
	StorageURL        string
	RangeStart        *int64
	RangeEnd          *int64
	BytesRequested    int64
	BytesCompleted    int64
	ActorEmail        string
	ActorSubject      string
	AuthMode          string
	ClientName        string
	ClientVersion     string
	TransferSessionID string
}

type FileCounterRecorder

type FileCounterRecorder interface {
	RecordFileUpload(ctx context.Context, objectID string) error
	RecordFileDownload(ctx context.Context, objectID string) error
}

FileCounterRecorder records object upload and download counters.

type FileUsageBatchQuery added in v0.4.2

type FileUsageBatchQuery struct {
	Scope         ScopeQuery
	ObjectIDs     []string
	InactiveSince *time.Time
}

FileUsageBatchQuery contains the domain inputs for a bulk usage report.

type FileUsageQuery

type FileUsageQuery struct {
	Scope         ScopeQuery
	Limit         int
	Offset        int
	InactiveSince *time.Time
}

FileUsageQuery is the explicit use-case input for a paged file report. Limit <= 0 retains the existing convention of returning the complete result; public adapters validate pagination bounds.

type FileUsageReader

type FileUsageReader interface {
	GetFileUsage(ctx context.Context, objectID string) (*metricsapi.FileUsage, error)
	ListFileUsageByObjectIDs(ctx context.Context, ids []string) ([]metricsapi.FileUsage, error)
	ListFileUsage(ctx context.Context, limit, offset int, inactiveSince *time.Time) ([]metricsapi.FileUsage, error)
	GetFileUsageSummary(ctx context.Context, inactiveSince *time.Time) (metricsapi.FileUsageSummary, error)
}

FileUsageReader reads per-object usage and unscoped reports.

type FileUsageSummaryQuery

type FileUsageSummaryQuery struct {
	Scope         ScopeQuery
	InactiveSince *time.Time
}

FileUsageSummaryQuery is the explicit use-case input for a file summary.

type Filter

type Filter struct {
	Organization         string
	Project              string
	EventType            string
	Direction            string
	From                 *time.Time
	To                   *time.Time
	Provider             string
	Bucket               string
	SHA256               string
	User                 string
	ReconciliationStatus string
}

type Grant

type Grant struct {
	AccessGrantID string
	FirstIssuedAt time.Time
	LastIssuedAt  time.Time
	IssueCount    int64
	ObjectID      string
	SHA256        string
	ObjectSize    int64
	Organization  string
	Project       string
	AccessID      string
	Provider      string
	Bucket        string
	StorageURL    string
	ActorEmail    string
	ActorSubject  string
	AuthMode      string
}

type ObjectReader

type ObjectReader interface {
	ResolveObjectIDs(ctx context.Context, requested []string) (map[string]string, error)
	ListReadableObjectIDsAmongScopes(ctx context.Context, scopes []objects.Scope, requested []string) ([]string, error)
}

ObjectReader resolves IDs and checks scoped read access for metrics objects.

type ProviderEventRecorder

type ProviderEventRecorder interface {
	RecordProviderTransferEvents(ctx context.Context, events []metricsapi.ProviderTransferEvent) error
}

ProviderEventRecorder records provider-reported transfer events.

type ReportStore

type ReportStore interface {
	FileUsageReader
	TransferQuery
	ListFileUsagePageByScope(ctx context.Context, organization, project string, limit, offset int, inactiveSince *time.Time) ([]metricsapi.FileUsage, error)
	ListFileUsagePageByResources(ctx context.Context, resources []string, includeUnscoped bool, limit, offset int, inactiveSince *time.Time) ([]metricsapi.FileUsage, error)
	GetFileUsageSummaryByScope(ctx context.Context, organization, project string, inactiveSince *time.Time) (metricsapi.FileUsageSummary, error)
	GetFileUsageSummaryByResources(ctx context.Context, resources []string, includeUnscoped bool, inactiveSince *time.Time) (metricsapi.FileUsageSummary, error)
	GetProjectRecordSummaryByScope(ctx context.Context, organization, project string) (metricsapi.FileUsageSummary, error)
}

type Reporter

type Reporter interface {
	GetFileUsage(ctx context.Context, objectID string) (*metricsapi.FileUsage, error)
	ListFileUsageBatch(ctx context.Context, query FileUsageBatchQuery) ([]metricsapi.FileUsage, error)
	GetScopedFileUsage(ctx context.Context, objectID string, scope ScopeQuery) (*metricsapi.FileUsage, error)
	ListFileUsage(ctx context.Context, query FileUsageQuery) ([]metricsapi.FileUsage, error)
	GetFileUsageSummary(ctx context.Context, query FileUsageSummaryQuery) (metricsapi.FileUsageSummary, error)
	GetTransferAttributionSummary(ctx context.Context, query TransferSummaryQuery) (metricsapi.TransferAttributionSummary, error)
	GetTransferAttributionBreakdown(ctx context.Context, query TransferBreakdownQuery) ([]metricsapi.TransferAttributionBreakdown, error)
}

type Scope

type Scope struct {
	Organization string
	Project      string
}

Scope identifies one organization/project authorization scope.

type ScopeQuery

type ScopeQuery struct {
	Organization    string
	Project         string
	Scopes          []Scope
	Resources       []string
	IncludeUnscoped bool
}

ScopeQuery describes an already-authorized report scope selection. An empty Organization means an unscoped report unless Scopes contains aggregate scopes. Resources are supplied by the authorization boundary for scoped persistence queries; usage deliberately does not know resource-path encoding.

func ResolveMetricsScope added in v0.4.2

func ResolveMetricsScope(ctx context.Context, selection ScopeSelection) (ScopeQuery, error)

ResolveMetricsScope applies the metrics read policy and returns the already-authorized report scope consumed by the usage service.

type ScopeSelection added in v0.4.2

type ScopeSelection struct {
	Organization string
	Project      string
}

ScopeSelection is the HTTP-neutral organization/project selection used by the metrics use case. Empty values request an aggregate or global report.

type Service

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

func NewService

func NewService(deps Dependencies) *Service

func (*Service) GetFileUsage

func (s *Service) GetFileUsage(ctx context.Context, objectID string) (*metricsapi.FileUsage, error)

func (*Service) GetFileUsageSummary

func (s *Service) GetFileUsageSummary(ctx context.Context, query FileUsageSummaryQuery) (metricsapi.FileUsageSummary, error)

GetFileUsageSummary routes scoped summaries through the required Store capability and supplements single-scope reports with record metadata.

func (*Service) GetScopedFileUsage added in v0.4.2

func (s *Service) GetScopedFileUsage(ctx context.Context, objectID string, scope ScopeQuery) (*metricsapi.FileUsage, error)

GetScopedFileUsage enforces object membership before exposing a single report. Inaccessible objects intentionally look absent at the HTTP boundary.

func (*Service) GetTransferAttributionBreakdown

func (s *Service) GetTransferAttributionBreakdown(ctx context.Context, query TransferBreakdownQuery) ([]metricsapi.TransferAttributionBreakdown, error)

GetTransferAttributionBreakdown preserves group validation and routes aggregate scope reports directly to the resource-scoped Store capability.

func (*Service) GetTransferAttributionSummary

func (s *Service) GetTransferAttributionSummary(ctx context.Context, query TransferSummaryQuery) (metricsapi.TransferAttributionSummary, error)

GetTransferAttributionSummary routes aggregate scope reports directly to the resource-scoped Store capability when no explicit organization filter exists.

func (*Service) ListFileUsage

func (s *Service) ListFileUsage(ctx context.Context, query FileUsageQuery) ([]metricsapi.FileUsage, error)

ListFileUsage routes scoped reports through the required Store capability.

func (*Service) ListFileUsageBatch added in v0.4.2

func (s *Service) ListFileUsageBatch(ctx context.Context, query FileUsageBatchQuery) ([]metricsapi.FileUsage, error)

ListFileUsageBatch normalizes requested IDs, filters them through the authorized scope, queries persistence once, and applies inactivity filtering without changing persistence order.

type TransferBreakdownQuery

type TransferBreakdownQuery struct {
	Filter  Filter
	GroupBy string
	Scope   ScopeQuery
	Limit   int
	Offset  int
}

TransferBreakdownQuery is the explicit use-case input for an attribution breakdown.

type TransferEventWriter

type TransferEventWriter interface {
	RecordTransferAttributionEvents(ctx context.Context, events []Event) error
}

type TransferQuery

type TransferQuery interface {
	QueryTransferSummary(ctx context.Context, filter Filter, resources []string) (metricsapi.TransferAttributionSummary, error)
	QueryTransferBreakdown(ctx context.Context, filter Filter, groupBy string, resources []string, limit, offset int) ([]metricsapi.TransferAttributionBreakdown, error)
}

TransferQuery reads transfer attribution reports.

type TransferSummaryQuery

type TransferSummaryQuery struct {
	Filter Filter
	Scope  ScopeQuery
}

TransferSummaryQuery is the explicit use-case input for an attribution summary. Aggregate scope selection is applied only when Filter.Organization is empty, matching the existing metrics behavior.

Jump to

Keyboard shortcuts

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