Documentation
¶
Overview ¶
Package reporting defines the agently-core reporting runtime boundary for canonical compile/fill/print-backed export operations.
Index ¶
- Constants
- Variables
- type Artifact
- type AuditEvent
- type AuditSink
- type CompileRequest
- type CompileResult
- type Compiler
- type CompleteExportRequest
- type Diagnostic
- type ExportFormat
- type ExportJob
- type ExportScope
- type Exporter
- type FailExportRequest
- type ForgeCSVExporter
- type ForgeExporter
- type ForgeExporterOptions
- type ForgePDFExporter
- type ForgePDFExporterOptions
- type ForgeXLSXExporter
- type GetArtifactInput
- type GetExportStatusInput
- type GetSharedArtifactInput
- type JobStatus
- type ListExportArtifactsInput
- type ListExportArtifactsResult
- type ListExportJobsInput
- type ListExportJobsResult
- type ListSharedArtifactsInput
- type ListSharedArtifactsResult
- type MemoryStore
- func (s *MemoryStore) CreateJob(_ context.Context, job *ExportJob) error
- func (s *MemoryStore) CreateSharedArtifact(_ context.Context, artifact *SharedArtifact) error
- func (s *MemoryStore) GetArtifact(_ context.Context, artifactID string) (*Artifact, error)
- func (s *MemoryStore) GetJob(_ context.Context, jobID string) (*ExportJob, error)
- func (s *MemoryStore) GetSharedArtifact(_ context.Context, artifactID string) (*SharedArtifact, error)
- func (s *MemoryStore) ListArtifacts(_ context.Context) ([]*Artifact, error)
- func (s *MemoryStore) ListJobs(_ context.Context) ([]*ExportJob, error)
- func (s *MemoryStore) ListSharedArtifacts(_ context.Context) ([]*SharedArtifact, error)
- func (s *MemoryStore) PutArtifact(_ context.Context, artifact *Artifact) error
- func (s *MemoryStore) UpdateJob(_ context.Context, job *ExportJob) error
- func (s *MemoryStore) UpdateSharedArtifact(_ context.Context, artifact *SharedArtifact) error
- type Options
- type RecordAuditEventInput
- type RenderRequest
- type RenderResult
- type ReportExportRequest
- type ReportExportSource
- type ReportExportTarget
- type ReportSpecCompiler
- type RunExportInput
- type RunQueuedExportsInput
- type RunQueuedExportsResult
- type Service
- func (s *Service) Compile(ctx context.Context, request *CompileRequest) (*CompileResult, error)
- func (s *Service) CompleteExport(ctx context.Context, request *CompleteExportRequest) (*ExportJob, error)
- func (s *Service) FailExport(ctx context.Context, request *FailExportRequest) (*ExportJob, error)
- func (s *Service) GetArtifact(ctx context.Context, artifactID string) (*Artifact, error)
- func (s *Service) GetExportStatus(ctx context.Context, jobID string) (*ExportJob, error)
- func (s *Service) GetSharedArtifact(ctx context.Context, artifactID string) (*SharedArtifact, error)
- func (s *Service) ListExportArtifacts(ctx context.Context, input *ListExportArtifactsInput) (*ListExportArtifactsResult, error)
- func (s *Service) ListExportJobs(ctx context.Context, input *ListExportJobsInput) (*ListExportJobsResult, error)
- func (s *Service) ListSharedArtifacts(ctx context.Context, input *ListSharedArtifactsInput) (*ListSharedArtifactsResult, error)
- func (s *Service) Method(name string) (svc.Executable, error)
- func (s *Service) Methods() svc.Signatures
- func (s *Service) Name() string
- func (s *Service) RecordAuditEvent(ctx context.Context, input *RecordAuditEventInput) (*AuditEvent, error)
- func (s *Service) RunExport(ctx context.Context, jobID string) (*ExportJob, error)
- func (s *Service) RunQueuedExports(ctx context.Context, limit int) (*RunQueuedExportsResult, error)
- func (s *Service) ShareArtifact(ctx context.Context, request *ShareArtifactRequest) (*SharedArtifact, error)
- func (s *Service) StartExport(ctx context.Context, jobID string) (*ExportJob, error)
- func (s *Service) SubmitExport(ctx context.Context, request *SubmitExportRequest) (*ExportJob, error)
- func (s *Service) TransitionArtifact(ctx context.Context, request *TransitionArtifactRequest) (*SharedArtifact, error)
- type ShareArtifactRequest
- type SharedArtifact
- type StartExportInput
- type Store
- type SubmitExportRequest
- type TransitionArtifactRequest
- type Worker
- type WorkerOptions
Constants ¶
const (
DefaultWorkerBatchLimit = 1
)
const Name = "reporting"
const (
SourceKindReportSpec = "reportSpec"
)
Variables ¶
var ( // ErrNotFound hides artifact/job existence across principals. ErrNotFound = errors.New("reporting: not found") // ErrJobNotQueued indicates a queued worker claim race or invalid lifecycle // transition when a caller tries to start a non-queued export job. ErrJobNotQueued = errors.New("reporting: job not queued") // ErrAlreadyExists indicates a storage collision on a generated reporting ID. ErrAlreadyExists = errors.New("reporting: already exists") )
Functions ¶
This section is empty.
Types ¶
type Artifact ¶
type Artifact struct {
ArtifactID string `json:"artifactId,omitempty"`
JobID string `json:"jobId,omitempty"`
ArtifactRef string `json:"artifactRef,omitempty"`
OwnerID string `json:"ownerId,omitempty"`
Format ExportFormat `json:"format,omitempty"`
ContentType string `json:"contentType,omitempty"`
Data []byte `json:"data,omitempty"`
CreatedAt time.Time `json:"createdAt,omitempty"`
RetentionTTL time.Duration `json:"retentionTtl,omitempty"`
}
Artifact is the downloadable export payload persisted by agently-core.
func (*Artifact) GetOwnerID ¶
type AuditEvent ¶
type AuditEvent struct {
EventType string `json:"eventType,omitempty"`
ArtifactRef string `json:"artifactRef,omitempty"`
Version int `json:"version,omitempty"`
JobID string `json:"jobId,omitempty"`
ArtifactID string `json:"artifactId,omitempty"`
ActorID string `json:"actorId,omitempty"`
ActorRef string `json:"actorRef,omitempty"`
OccurredAt time.Time `json:"occurredAt,omitempty"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
}
AuditEvent is the generic reporting audit payload emitted by the service.
type AuditSink ¶
type AuditSink interface {
Record(ctx context.Context, event *AuditEvent) error
}
AuditSink records reporting lifecycle events.
type CompileRequest ¶
type CompileRequest struct {
ArtifactRef string `json:"artifactRef,omitempty"`
SourceKind string `json:"sourceKind,omitempty"`
Document json.RawMessage `json:"document,omitempty"`
}
CompileRequest carries an authored artifact into the backend compile seam.
type CompileResult ¶
type CompileResult struct {
ArtifactRef string `json:"artifactRef,omitempty"`
ReportSpec json.RawMessage `json:"reportSpec,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
CompiledAt time.Time `json:"compiledAt,omitempty"`
}
CompileResult is the canonical compile response.
type Compiler ¶
type Compiler interface {
Compile(ctx context.Context, request *CompileRequest) (*CompileResult, error)
}
Compiler lowers authored artifacts into canonical ReportSpec payloads.
type CompleteExportRequest ¶
type CompleteExportRequest struct {
JobID string `json:"jobId,omitempty"`
ContentType string `json:"contentType,omitempty"`
Data []byte `json:"data,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
RetentionTTL time.Duration `json:"retentionTtl,omitempty"`
}
CompleteExportRequest records a successful export artifact.
type Diagnostic ¶
type Diagnostic struct {
Code string `json:"code,omitempty"`
Severity string `json:"severity,omitempty"`
Path string `json:"path,omitempty"`
Message string `json:"message,omitempty"`
SuggestedFix string `json:"suggestedFix,omitempty"`
}
Diagnostic is the structured backend diagnostic shape used across compile and export operations.
type ExportFormat ¶
type ExportFormat string
ExportFormat identifies the requested artifact type.
const ( ExportFormatPDF ExportFormat = "pdf" ExportFormatCSV ExportFormat = "csv" ExportFormatXLSX ExportFormat = "xlsx" )
type ExportJob ¶
type ExportJob struct {
JobID string `json:"jobId,omitempty"`
ArtifactRef string `json:"artifactRef,omitempty"`
OwnerID string `json:"ownerId,omitempty"`
Format ExportFormat `json:"format,omitempty"`
Scope ExportScope `json:"scope,omitempty"`
Status JobStatus `json:"status,omitempty"`
ReportSpec json.RawMessage `json:"reportSpec,omitempty"`
ReportFill json.RawMessage `json:"reportFill,omitempty"`
ReportPrint json.RawMessage `json:"reportPrint,omitempty"`
ArtifactID string `json:"artifactId,omitempty"`
Error string `json:"error,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
SubmittedAt time.Time `json:"submittedAt,omitempty"`
StartedAt *time.Time `json:"startedAt,omitempty"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
RetentionTTL time.Duration `json:"retentionTtl,omitempty"`
}
ExportJob is the persisted async export job state.
func (*ExportJob) GetOwnerID ¶
type ExportScope ¶
type ExportScope string
ExportScope identifies the export source lifecycle.
const ( ExportScopeDraft ExportScope = "draft" ExportScopeSavedPayload ExportScope = "saved_payload" ExportScopeSavedView ExportScope = "saved_view" ExportScopePublishedSnapshot ExportScope = "published_snapshot" )
type Exporter ¶
type Exporter interface {
Export(ctx context.Context, request *RenderRequest) (*RenderResult, error)
}
Exporter turns canonical report artifacts into a persisted downloadable artifact without re-interpreting authoring semantics.
func NewForgeCSVExporter ¶
func NewForgeCSVExporter() Exporter
func NewForgeExporter ¶
func NewForgeExporter(options *ForgeExporterOptions) Exporter
func NewForgePDFExporter ¶
func NewForgePDFExporter(options *ForgePDFExporterOptions) Exporter
NewForgePDFExporter constructs a Forge-backed PDF exporter.
func NewForgeXLSXExporter ¶
func NewForgeXLSXExporter() Exporter
type FailExportRequest ¶
type FailExportRequest struct {
JobID string `json:"jobId,omitempty"`
Error string `json:"error,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}
FailExportRequest records a failed export result.
type ForgeCSVExporter ¶
type ForgeCSVExporter struct{}
func (*ForgeCSVExporter) Export ¶
func (e *ForgeCSVExporter) Export(_ context.Context, request *RenderRequest) (*RenderResult, error)
type ForgeExporter ¶
type ForgeExporter struct {
// contains filtered or unexported fields
}
func (*ForgeExporter) Export ¶
func (e *ForgeExporter) Export(ctx context.Context, request *RenderRequest) (*RenderResult, error)
type ForgeExporterOptions ¶
type ForgeExporterOptions struct {
PDF *ForgePDFExporterOptions
}
type ForgePDFExporter ¶
type ForgePDFExporter struct {
// contains filtered or unexported fields
}
ForgePDFExporter renders canonical ReportPrint payloads into deterministic PDF bytes using Forge's Go export engine.
func (*ForgePDFExporter) Export ¶
func (e *ForgePDFExporter) Export(_ context.Context, request *RenderRequest) (*RenderResult, error)
Export renders a canonical ReportPrint payload into PDF bytes.
type ForgePDFExporterOptions ¶
ForgePDFExporterOptions configures the canonical Forge-backed PDF exporter.
type ForgeXLSXExporter ¶
type ForgeXLSXExporter struct{}
func (*ForgeXLSXExporter) Export ¶
func (e *ForgeXLSXExporter) Export(_ context.Context, request *RenderRequest) (*RenderResult, error)
type GetArtifactInput ¶
type GetArtifactInput struct {
ArtifactID string `json:"artifactId,omitempty"`
}
type GetExportStatusInput ¶
type GetExportStatusInput struct {
JobID string `json:"jobId,omitempty"`
}
type GetSharedArtifactInput ¶
type GetSharedArtifactInput struct {
}
type ListExportArtifactsInput ¶
type ListExportArtifactsInput struct {
ArtifactRef string `json:"artifactRef,omitempty"`
JobID string `json:"jobId,omitempty"`
Format ExportFormat `json:"format,omitempty"`
Limit int `json:"limit,omitempty"`
}
type ListExportJobsInput ¶
type ListExportJobsInput struct {
ArtifactRef string `json:"artifactRef,omitempty"`
Format ExportFormat `json:"format,omitempty"`
Scope ExportScope `json:"scope,omitempty"`
Status JobStatus `json:"status,omitempty"`
Limit int `json:"limit,omitempty"`
}
type ListExportJobsResult ¶
type ListSharedArtifactsInput ¶
type ListSharedArtifactsInput struct {
}
type ListSharedArtifactsResult ¶
type ListSharedArtifactsResult struct {
}
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is the simplest in-process reporting store. It is intended for scaffolding, tests, and bootstrap paths before durable Datly persistence is wired in.
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
NewMemoryStore constructs an empty in-memory reporting store.
func (*MemoryStore) CreateJob ¶
func (s *MemoryStore) CreateJob(_ context.Context, job *ExportJob) error
CreateJob persists a queued export job.
func (*MemoryStore) CreateSharedArtifact ¶
func (s *MemoryStore) CreateSharedArtifact(_ context.Context, artifact *SharedArtifact) error
CreateSharedArtifact persists a shared reporting artifact.
func (*MemoryStore) GetArtifact ¶
GetArtifact returns a cloned export artifact.
func (*MemoryStore) GetSharedArtifact ¶
func (s *MemoryStore) GetSharedArtifact(_ context.Context, artifactID string) (*SharedArtifact, error)
GetSharedArtifact returns a cloned shared reporting artifact.
func (*MemoryStore) ListArtifacts ¶
func (s *MemoryStore) ListArtifacts(_ context.Context) ([]*Artifact, error)
ListArtifacts returns cloned export artifacts in unspecified order.
func (*MemoryStore) ListJobs ¶
func (s *MemoryStore) ListJobs(_ context.Context) ([]*ExportJob, error)
ListJobs returns cloned export jobs in unspecified order.
func (*MemoryStore) ListSharedArtifacts ¶
func (s *MemoryStore) ListSharedArtifacts(_ context.Context) ([]*SharedArtifact, error)
ListSharedArtifacts returns cloned shared reporting artifacts in unspecified order.
func (*MemoryStore) PutArtifact ¶
func (s *MemoryStore) PutArtifact(_ context.Context, artifact *Artifact) error
PutArtifact stores a completed export artifact.
func (*MemoryStore) UpdateJob ¶
func (s *MemoryStore) UpdateJob(_ context.Context, job *ExportJob) error
UpdateJob replaces a persisted export job.
func (*MemoryStore) UpdateSharedArtifact ¶
func (s *MemoryStore) UpdateSharedArtifact(_ context.Context, artifact *SharedArtifact) error
UpdateSharedArtifact replaces a persisted shared reporting artifact.
type Options ¶
type Options struct {
Compiler Compiler
Exporter Exporter
Store Store
Audit AuditSink
Now func() time.Time
NewID func() string
}
Options configures a reporting Service.
type RecordAuditEventInput ¶
type RecordAuditEventInput struct {
Event *AuditEvent `json:"event,omitempty"`
}
RecordAuditEventInput carries a UI-originated reporting audit event through the reporting service boundary.
type RenderRequest ¶
type RenderRequest struct {
JobID string `json:"jobId,omitempty"`
ArtifactRef string `json:"artifactRef,omitempty"`
OwnerID string `json:"ownerId,omitempty"`
Format ExportFormat `json:"format,omitempty"`
Scope ExportScope `json:"scope,omitempty"`
ReportSpec json.RawMessage `json:"reportSpec,omitempty"`
ReportFill json.RawMessage `json:"reportFill,omitempty"`
ReportPrint json.RawMessage `json:"reportPrint,omitempty"`
}
RenderRequest is the worker-facing canonical export payload handed to the backend exporter boundary.
type RenderResult ¶
type RenderResult struct {
ContentType string `json:"contentType,omitempty"`
Data []byte `json:"data,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
RetentionTTL time.Duration `json:"retentionTtl,omitempty"`
}
RenderResult is the exporter output consumed by agently-core artifact persistence.
type ReportExportRequest ¶
type ReportExportRequest struct {
Version int `json:"version,omitempty"`
Kind string `json:"kind,omitempty"`
Target ReportExportTarget `json:"target,omitempty"`
Source ReportExportSource `json:"source,omitempty"`
ReportSpec json.RawMessage `json:"reportSpec,omitempty"`
ReportFill json.RawMessage `json:"reportFill,omitempty"`
ReportPrint json.RawMessage `json:"reportPrint,omitempty"`
}
ReportExportRequest is the canonical Forge export handoff envelope accepted by agently-core reporting export submission.
type ReportExportSource ¶
type ReportExportSource struct {
From string `json:"from,omitempty"`
ArtifactKind string `json:"artifactKind,omitempty"`
ArtifactRef string `json:"artifactRef,omitempty"`
Title string `json:"title,omitempty"`
ReportID string `json:"reportId,omitempty"`
PayloadID string `json:"payloadId,omitempty"`
SourceArtifactID string `json:"sourceArtifactId,omitempty"`
DocumentVersion int `json:"documentVersion,omitempty"`
}
type ReportExportTarget ¶
type ReportExportTarget struct {
Format ExportFormat `json:"format,omitempty"`
}
type ReportSpecCompiler ¶
type ReportSpecCompiler struct {
// contains filtered or unexported fields
}
ReportSpecCompiler is the first backend compile implementation. It accepts already-canonical ReportSpec payloads and validates the top-level contract before returning them to the runtime. It does not lower raw authoring artifacts yet.
func NewReportSpecCompiler ¶
func NewReportSpecCompiler(now func() time.Time) *ReportSpecCompiler
NewReportSpecCompiler constructs a compiler for canonical ReportSpec inputs.
func (*ReportSpecCompiler) Compile ¶
func (c *ReportSpecCompiler) Compile(_ context.Context, request *CompileRequest) (*CompileResult, error)
Compile validates and returns a canonical ReportSpec payload.
type RunExportInput ¶
type RunExportInput struct {
JobID string `json:"jobId,omitempty"`
}
type RunQueuedExportsInput ¶
type RunQueuedExportsInput struct {
Limit int `json:"limit,omitempty"`
}
type RunQueuedExportsResult ¶
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the agently-core runtime boundary for reporting compile and export job orchestration.
func (*Service) Compile ¶
func (s *Service) Compile(ctx context.Context, request *CompileRequest) (*CompileResult, error)
Compile runs the configured canonical compiler.
func (*Service) CompleteExport ¶
func (s *Service) CompleteExport(ctx context.Context, request *CompleteExportRequest) (*ExportJob, error)
CompleteExport persists a finished export artifact and marks the job succeeded.
func (*Service) FailExport ¶
FailExport marks an export job failed.
func (*Service) GetArtifact ¶
GetArtifact returns an artifact visible to the current principal.
func (*Service) GetExportStatus ¶
GetExportStatus returns a job visible to the current principal.
func (*Service) GetSharedArtifact ¶
func (s *Service) GetSharedArtifact(ctx context.Context, artifactID string) (*SharedArtifact, error)
GetSharedArtifact returns a shared artifact visible to the current principal.
func (*Service) ListExportArtifacts ¶
func (s *Service) ListExportArtifacts(ctx context.Context, input *ListExportArtifactsInput) (*ListExportArtifactsResult, error)
ListExportArtifacts returns export artifacts visible to the current principal.
func (*Service) ListExportJobs ¶
func (s *Service) ListExportJobs(ctx context.Context, input *ListExportJobsInput) (*ListExportJobsResult, error)
ListExportJobs returns export jobs visible to the current principal.
func (*Service) ListSharedArtifacts ¶
func (s *Service) ListSharedArtifacts(ctx context.Context, input *ListSharedArtifactsInput) (*ListSharedArtifactsResult, error)
ListSharedArtifacts returns shared artifacts visible to the current principal.
func (*Service) Methods ¶
func (s *Service) Methods() svc.Signatures
func (*Service) RecordAuditEvent ¶
func (s *Service) RecordAuditEvent(ctx context.Context, input *RecordAuditEventInput) (*AuditEvent, error)
RecordAuditEvent validates and records a structured reporting audit event.
func (*Service) RunExport ¶
RunExport executes a queued job through the configured exporter boundary and persists either a completed artifact or a failed job state.
func (*Service) RunQueuedExports ¶
RunQueuedExports executes queued jobs in submitted order up to limit.
func (*Service) ShareArtifact ¶
func (s *Service) ShareArtifact(ctx context.Context, request *ShareArtifactRequest) (*SharedArtifact, error)
ShareArtifact creates or returns a shared artifact such as a saved view.
func (*Service) StartExport ¶
StartExport marks a queued job running. Intended for async workers.
func (*Service) SubmitExport ¶
func (s *Service) SubmitExport(ctx context.Context, request *SubmitExportRequest) (*ExportJob, error)
SubmitExport enqueues a canonical export job.
func (*Service) TransitionArtifact ¶
func (s *Service) TransitionArtifact(ctx context.Context, request *TransitionArtifactRequest) (*SharedArtifact, error)
TransitionArtifact mutates lifecycle state or materializes a published snapshot.
type ShareArtifactRequest ¶
type ShareArtifactRequest struct {
}
ShareArtifactRequest creates or returns a shared reporting artifact through the reporting persistence boundary.
type SharedArtifact ¶
type SharedArtifact struct {
}
SharedArtifact is the persisted saved-view / published-snapshot shell owned by agently-core. Payload fields remain opaque JSON at this boundary.
func (*SharedArtifact) GetOwnerID ¶
func (a *SharedArtifact) GetOwnerID() string
type StartExportInput ¶
type StartExportInput struct {
JobID string `json:"jobId,omitempty"`
}
type Store ¶
type Store interface {
CreateJob(ctx context.Context, job *ExportJob) error
GetJob(ctx context.Context, jobID string) (*ExportJob, error)
ListJobs(ctx context.Context) ([]*ExportJob, error)
UpdateJob(ctx context.Context, job *ExportJob) error
PutArtifact(ctx context.Context, artifact *Artifact) error
GetArtifact(ctx context.Context, artifactID string) (*Artifact, error)
ListArtifacts(ctx context.Context) ([]*Artifact, error)
}
Store persists export jobs and artifacts.
func NewStoreAdapter ¶
func NewStoreAdapter(client reportstore.Client) Store
NewStoreAdapter bridges the generic reporting store client into the reporting service's Store interface.
type SubmitExportRequest ¶
type SubmitExportRequest struct {
ArtifactRef string `json:"artifactRef,omitempty"`
Format ExportFormat `json:"format,omitempty"`
Scope ExportScope `json:"scope,omitempty"`
ReportSpec json.RawMessage `json:"reportSpec,omitempty"`
ReportFill json.RawMessage `json:"reportFill,omitempty"`
ReportPrint json.RawMessage `json:"reportPrint,omitempty"`
ReportExportRequest *ReportExportRequest `json:"reportExportRequest,omitempty"`
}
SubmitExportRequest queues an export job against canonical reporting models.
type TransitionArtifactRequest ¶
type TransitionArtifactRequest struct {
ArtifactRef string `json:"artifactRef,omitempty"`
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
Reason string `json:"reason,omitempty"`
Version int `json:"version,omitempty"`
ReportDocument json.RawMessage `json:"reportDocument,omitempty"`
ReportExportRequest *ReportExportRequest `json:"reportExportRequest,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
}
TransitionArtifactRequest mutates or materializes a lifecycle transition through the reporting persistence boundary.