usage

package
v0.4.1 Latest Latest
Warning

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

Go to latest
Published: Sep 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TransferEventAccessIssued = "access_issued"

	ProviderTransferDirectionDownload = "download"
	ProviderTransferDirectionUpload   = "upload"

	ProviderTransferMatched   = "matched"
	ProviderTransferAmbiguous = "ambiguous"
	ProviderTransferUnmatched = "unmatched"
)

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

Types

type Breakdown

type Breakdown struct {
	Key              string     `json:"key"`
	Organization     string     `json:"organization"`
	Project          string     `json:"project"`
	Provider         string     `json:"provider"`
	Bucket           string     `json:"bucket"`
	SHA256           string     `json:"sha256"`
	ActorEmail       string     `json:"actor_email"`
	ActorSubject     string     `json:"actor_subject"`
	EventCount       int64      `json:"event_count"`
	BytesRequested   int64      `json:"bytes_requested"`
	BytesDownloaded  int64      `json:"bytes_downloaded"`
	BytesUploaded    int64      `json:"bytes_uploaded"`
	LastTransferTime *time.Time `json:"last_transfer_time"`
}

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 FileUsage

type FileUsage struct {
	ObjectID         string
	Name             string
	Size             int64
	UploadCount      int64
	DownloadCount    int64
	LastUploadTime   *time.Time
	LastDownloadTime *time.Time
	LastAccessTime   *time.Time
}

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 fallback result; public adapters validate pagination bounds.

type FileUsageReader

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

FileUsageReader reads per-object usage and unscoped reports.

type FileUsageSummary

type FileUsageSummary struct {
	TotalFiles              int64
	TotalUploads            int64
	TotalDownloads          int64
	InactiveFileCount       int64
	RecordCount             int64
	RecordLatestUpdatedTime *time.Time
}

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 Freshness

type Freshness struct {
	IsStale             bool       `json:"is_stale"`
	MissingBuckets      []string   `json:"missing_buckets,omitempty"`
	LatestCompletedSync *time.Time `json:"latest_completed_sync,omitempty"`
	RequiredFrom        *time.Time `json:"required_from,omitempty"`
	RequiredTo          *time.Time `json:"required_to,omitempty"`
}

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 {
	GetObject(ctx context.Context, ident, requiredMethod string) (*objects.Record, error)
	ListObjectIDsByScope(ctx context.Context, organization, project, requiredMethod string) ([]string, error)
}

ObjectReader reads objects for metrics authorization and fallback reports. requiredMethod is supplied by callers so the object service can enforce the same access method as the existing metrics paths.

type OptionalScopedFileUsageQuery

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

OptionalScopedFileUsageQuery is an optional optimization for authorized metrics queries. Callers retain a per-object fallback when it is unavailable.

type OptionalScopedTransferQuery

type OptionalScopedTransferQuery interface {
	GetTransferAttributionSummaryByResources(ctx context.Context, filter Filter, resources []string) (Summary, error)
	GetTransferAttributionBreakdownByResources(ctx context.Context, filter Filter, groupBy string, resources []string) ([]Breakdown, error)
}

OptionalScopedTransferQuery is an optional optimization for authorized transfer reports. Callers retain a per-scope fallback when it is unavailable.

type ProviderEvent

type ProviderEvent struct {
	ProviderEventID      string
	AccessGrantID        string
	Direction            string
	EventTime            time.Time
	RequestID            string
	ProviderRequestID    string
	ObjectID             string
	SHA256               string
	ObjectSize           int64
	Organization         string
	Project              string
	AccessID             string
	Provider             string
	Bucket               string
	ObjectKey            string
	StorageURL           string
	RangeStart           *int64
	RangeEnd             *int64
	BytesTransferred     int64
	HTTPMethod           string
	HTTPStatus           int
	RequesterPrincipal   string
	SourceIP             string
	UserAgent            string
	RawEventRef          string
	ActorEmail           string
	ActorSubject         string
	AuthMode             string
	ReconciliationStatus string
}

type ProviderEventRecorder

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

ProviderEventRecorder records provider-reported transfer events.

type ReportStore

type ReportStore interface {
	FileUsageReader
	TransferQuery
}

type Reporter

type Reporter interface {
	GetFileUsage(ctx context.Context, objectID string) (*FileUsage, error)
	ListFileUsageByObjectIDs(ctx context.Context, ids []string) ([]FileUsage, error)
	ListReadableObjectIDs(ctx context.Context, scope ScopeQuery, requested []string) ([]string, error)
	ListFileUsage(ctx context.Context, query FileUsageQuery) ([]FileUsage, error)
	GetFileUsageSummary(ctx context.Context, query FileUsageSummaryQuery) (FileUsageSummary, error)
	GetTransferAttributionSummary(ctx context.Context, query TransferSummaryQuery) (Summary, error)
	GetTransferAttributionBreakdown(ctx context.Context, query TransferBreakdownQuery) ([]Breakdown, error)
	GetTransferFreshness(ctx context.Context, filter Filter) (Freshness, 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 explicitly for the optional persistence fast path; usage deliberately does not know resource-path encoding.

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) (*FileUsage, error)

func (*Service) GetFileUsageSummary

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

GetFileUsageSummary chooses the scoped optimization when available and preserves fallback record-count and inactive-file semantics.

func (*Service) GetTransferAttributionBreakdown

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

GetTransferAttributionBreakdown preserves group validation, scoped optimization, fallback merging, and latest-transfer ordering.

func (*Service) GetTransferAttributionSummary

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

GetTransferAttributionSummary chooses the scoped optimization only for an aggregate selection without an explicit organization filter.

func (*Service) GetTransferFreshness

func (s *Service) GetTransferFreshness(_ context.Context, filter Filter) (Freshness, error)

func (*Service) ListFileUsage

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

ListFileUsage chooses a scoped persistence optimization when available and otherwise runs the object-authorized fallback aggregation used by metrics.

func (*Service) ListFileUsageByObjectIDs

func (s *Service) ListFileUsageByObjectIDs(ctx context.Context, ids []string) ([]FileUsage, error)

func (*Service) ListReadableObjectIDs

func (s *Service) ListReadableObjectIDs(ctx context.Context, scope ScopeQuery, requested []string) ([]string, error)

ListReadableObjectIDs resolves scope membership from the object reader and returns only requested IDs in their original order. Unscoped callers retain the existing behavior of passing requests through unchanged.

func (*Service) Reports

func (s *Service) Reports() Reporter

type Summary

type Summary struct {
	EventCount         int64      `json:"event_count"`
	AccessIssuedCount  int64      `json:"access_issued_count"`
	DownloadEventCount int64      `json:"download_event_count"`
	UploadEventCount   int64      `json:"upload_event_count"`
	BytesRequested     int64      `json:"bytes_requested"`
	BytesDownloaded    int64      `json:"bytes_downloaded"`
	BytesUploaded      int64      `json:"bytes_uploaded"`
	Freshness          *Freshness `json:"freshness,omitempty"`
}

type TransferBreakdownQuery

type TransferBreakdownQuery struct {
	Filter  Filter
	GroupBy string
	Scope   ScopeQuery
}

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 {
	GetTransferAttributionSummary(ctx context.Context, filter Filter) (Summary, error)
	GetTransferAttributionBreakdown(ctx context.Context, filter Filter, groupBy string) ([]Breakdown, 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