Documentation
¶
Index ¶
- Constants
- Variables
- func EventID(event Event) string
- func GrantID(event Event) string
- type Breakdown
- type Dependencies
- type Event
- type FileCounterRecorder
- type FileUsage
- type FileUsageQuery
- type FileUsageReader
- type FileUsageSummary
- type FileUsageSummaryQuery
- type Filter
- type Freshness
- type Grant
- type Ingestor
- type ObjectReader
- type OptionalScopedFileUsageQuery
- type OptionalScopedTransferQuery
- type ProviderEvent
- type ProviderEventRecorder
- type ReportStore
- type Reporter
- type Scope
- type ScopeQuery
- type Service
- func (s *Service) GetFileUsage(ctx context.Context, objectID string) (*FileUsage, error)
- func (s *Service) GetFileUsageSummary(ctx context.Context, query FileUsageSummaryQuery) (FileUsageSummary, error)
- func (s *Service) GetTransferAttributionBreakdown(ctx context.Context, query TransferBreakdownQuery) ([]Breakdown, error)
- func (s *Service) GetTransferAttributionSummary(ctx context.Context, query TransferSummaryQuery) (Summary, error)
- func (s *Service) GetTransferFreshness(_ context.Context, filter Filter) (Freshness, error)
- func (s *Service) ListFileUsage(ctx context.Context, query FileUsageQuery) ([]FileUsage, error)
- func (s *Service) ListFileUsageByObjectIDs(ctx context.Context, ids []string) ([]FileUsage, error)
- func (s *Service) ListReadableObjectIDs(ctx context.Context, scope ScopeQuery, requested []string) ([]string, error)
- func (s *Service) Reports() Reporter
- type Summary
- type TransferBreakdownQuery
- type TransferEventWriter
- type TransferQuery
- type TransferSummaryQuery
Constants ¶
const ( TransferEventAccessIssued = "access_issued" ProviderTransferDirectionDownload = "download" ProviderTransferDirectionUpload = "upload" ProviderTransferMatched = "matched" ProviderTransferAmbiguous = "ambiguous" ProviderTransferUnmatched = "unmatched" )
Variables ¶
var ( ErrInvalidGroupBy = errors.New("invalid transfer breakdown group_by") )
Functions ¶
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 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 FileUsageSummaryQuery ¶
type FileUsageSummaryQuery struct {
Scope ScopeQuery
InactiveSince *time.Time
}
FileUsageSummaryQuery is the explicit use-case input for a file summary.
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 Ingestor ¶
type Ingestor interface {
FileCounterRecorder
TransferEventWriter
ProviderEventRecorder
}
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 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 (*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 (*Service) ListFileUsage ¶
ListFileUsage chooses a scoped persistence optimization when available and otherwise runs the object-authorized fallback aggregation used by metrics.
func (*Service) ListFileUsageByObjectIDs ¶
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.
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 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.