document

package
v0.23.0 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package document turns a template plus data into a stored PDF with metadata: the template is executed with html/template, the resulting HTML is converted to PDF by a swappable Renderer, the bytes are uploaded through storage.Storage, and a metadata row (case, template, version, sha256, storage key, verification key) is persisted through a Repository.

The package deliberately knows nothing about the workflow engine beyond plain identifiers: a Document references a (Domain, ExternalID) pair and, optionally, a case id, exactly the way a workflow.Case references its business object. That keeps it usable outside the engine (a certificate issued by a plain HTTP handler, a batch job) and leaves wiring it as a workflow effect to a separate package.

Electronic signature is out of scope: only the Signer port is declared.

Index

Constants

View Source
const ContentType = "application/pdf"

ContentType is the MIME type every generated document is stored with.

View Source
const DefaultCleanupTimeout = 10 * time.Second

DefaultCleanupTimeout is the Config.CleanupTimeout used when it is zero.

View Source
const DefaultKeyPrefix = "documents"

DefaultKeyPrefix is the storage key prefix used when Config.KeyPrefix is empty.

Variables

View Source
var (
	ErrNotFound     = errors.New("document: not found")
	ErrInvalidInput = errors.New("document: invalid input")
	// ErrTemplate reports that a template failed to parse or execute (for
	// example a key missing from the data). Retrying the same input cannot
	// fix it.
	ErrTemplate = errors.New("document: template failed")
	// ErrEmptyPDF reports that the Renderer returned no bytes; nothing is
	// uploaded or stored.
	ErrEmptyPDF = errors.New("document: renderer returned an empty pdf")
	// ErrRenderRejected is wrapped by a Renderer error that retrying the
	// same HTML cannot fix (the renderer refused or could not convert it),
	// as opposed to an outage or a timeout worth retrying.
	ErrRenderRejected = errors.New("document: renderer rejected the document")
)

Sentinel errors callers can branch on via errors.Is.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Now returns the current time. Nil uses time.Now — inject a fixed clock
	// in tests.
	Now func() time.Time
	// KeyPrefix is the storage key prefix. Empty uses DefaultKeyPrefix.
	KeyPrefix string
	// CleanupTimeout bounds the best-effort Delete Generate runs after a
	// failed insert. Zero uses DefaultCleanupTimeout.
	CleanupTimeout time.Duration
}

Config configures optional Service behaviour.

type Document

type Document struct {
	ID         uuid.UUID
	Domain     string
	ExternalID string
	// CaseID is the workflow case the document belongs to, when any. It is
	// a plain identifier: this package never reads the case.
	CaseID          *uuid.UUID
	TemplateName    string
	TemplateVersion int
	// SHA256 is the lowercase hex digest of the stored PDF bytes.
	SHA256     string
	StorageKey string
	// VerificationKey is a random, URL-safe token (crypto/rand) a public
	// verification endpoint can look the document up by, without exposing
	// the internal ID or the storage key.
	VerificationKey string
	Size            int64
	// SourceKey identifies what produced the document (for example one
	// workflow effect run). Empty means none. Generate returns the existing
	// document for a known non-empty SourceKey instead of generating again,
	// so a retried job never creates a duplicate.
	SourceKey string
	CreatedAt time.Time
}

Document is the metadata record of one generated PDF. The bytes themselves live in object storage under StorageKey.

type GenerateInput

type GenerateInput struct {
	Domain     string
	ExternalID string
	// CaseID optionally ties the document to a workflow case.
	CaseID   *uuid.UUID
	Template Template
	// Data is the value the template is executed against.
	Data any
	// SourceKey optionally identifies what asked for the document; see
	// Document.SourceKey.
	SourceKey string
}

GenerateInput is what Service.Generate needs to produce one document.

type Renderer

type Renderer interface {
	Render(ctx context.Context, html []byte) ([]byte, error)
}

Renderer converts an HTML document to PDF bytes. Implementations must be safe for concurrent use, and wrap ErrRenderRejected in errors a retry cannot fix. The first adapter is document/gotenberg.

type Repository

type Repository interface {
	// Insert persists d. A duplicate id, storage key or verification key is
	// an error.
	Insert(ctx context.Context, db pgxtx.DBTX, d *Document) error
	// GetByID returns the document with id, or an error wrapping
	// ErrNotFound.
	GetByID(ctx context.Context, db pgxtx.DBTX, id uuid.UUID) (*Document, error)
	// ListByCase returns every document of caseID ordered by creation time
	// (oldest first); an empty result is not an error.
	ListByCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]Document, error)
	// GetByVerificationKey returns the document whose verification key is
	// key, or an error wrapping ErrNotFound.
	GetByVerificationKey(ctx context.Context, db pgxtx.DBTX, key string) (*Document, error)
	// GetBySourceKey returns the document whose source key is key, or an
	// error wrapping ErrNotFound.
	GetBySourceKey(ctx context.Context, db pgxtx.DBTX, key string) (*Document, error)
	// ExistsForCase reports whether caseID has at least one document of
	// templateName, in any template version.
	ExistsForCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID, templateName string) (bool, error)
}

Repository persists Document metadata. Every method receives the pgxtx.DBTX to run against, so the caller decides whether it runs inside its own transaction.

type Service

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

Service generates, stores and looks up documents.

func NewService

func NewService(repo Repository, store storage.Storage, renderer Renderer, cfg Config, logger *slog.Logger) *Service

NewService creates a Service. A nil logger falls back to slog.Default().

func (*Service) ExistsForCase

func (s *Service) ExistsForCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID, templateName string) (bool, error)

ExistsForCase reports whether caseID has at least one document of templateName, in any template version.

func (*Service) FindByVerificationKey

func (s *Service) FindByVerificationKey(ctx context.Context, db pgxtx.DBTX, key string) (*Document, error)

FindByVerificationKey returns the document a public verification endpoint was asked about. An empty key is ErrNotFound without querying.

func (*Service) Generate

func (s *Service) Generate(ctx context.Context, db pgxtx.DBTX, in GenerateInput) (*Document, error)

Generate executes in.Template against in.Data, renders the HTML to PDF, uploads it and inserts its metadata row through db, returning the stored Document.

The storage key is <prefix>/<domain>/<case id or external id>/<document id>.pdf, each segment path-escaped. Every step runs in order and stops at the first failure:

  • invalid input or a template error: nothing is rendered;
  • a Renderer error (or an empty PDF): nothing is uploaded or stored;
  • an upload error: no metadata row is inserted;
  • an insert error after a successful upload: Generate attempts a best-effort Delete of the uploaded object and returns the original insert error. A failed Delete is logged, not returned, and leaves an orphan object with no metadata row; nothing references it, so it is safe to sweep later.

When db is a transaction that later rolls back, the metadata row disappears but the uploaded object does not: object storage is not transactional. Callers that care sweep objects with no metadata row.

func (*Service) Get

func (s *Service) Get(ctx context.Context, db pgxtx.DBTX, id uuid.UUID) (*Document, error)

Get returns the document with id, or an error wrapping ErrNotFound.

func (*Service) ListByCase

func (s *Service) ListByCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]Document, error)

ListByCase returns every document of caseID, oldest first.

type Signer

type Signer interface {
	Sign(ctx context.Context, pdf []byte) ([]byte, error)
}

Signer applies an electronic signature to PDF bytes and returns the signed PDF. Only the port is declared: signing is out of scope for this package and no implementation is provided. A consumer that needs signed documents supplies its own Signer and applies it around a Renderer.

type Template

type Template struct {
	Name    string
	Version int
	Body    string
}

Template is a named, versioned HTML template. Body is parsed and executed with html/template, so every value interpolated from the data is escaped for its HTML context automatically: a field containing "<script>" is rendered as text, never as markup. Unlike a plain string substitution, template data can never inject HTML into the generated document.

func (Template) Execute

func (t Template) Execute(data any) ([]byte, error)

Execute parses Body and executes it against data, returning the HTML. A reference to a missing map key is an error (missingkey=error), so a typo in a template fails loudly instead of rendering an empty value.

Directories

Path Synopsis
Package docflow connects document to the workflow engine and the action runner: Generate is the handler behind a "document.generate" effect, and Exists is the guard that keeps a case from advancing until a document of a given template exists for it.
Package docflow connects document to the workflow engine and the action runner: Generate is the handler behind a "document.generate" effect, and Exists is the guard that keeps a case from advancing until a document of a given template exists for it.
Package gotenberg is a document.Renderer backed by a Gotenberg server's Chromium HTML route.
Package gotenberg is a document.Renderer backed by a Gotenberg server's Chromium HTML route.
Package migrations embeds the SQL migration(s) that create the document table this library owns.
Package migrations embeds the SQL migration(s) that create the document table this library owns.
Package postgres provides the PostgreSQL-backed implementation of the document.Repository port, built on native pgx.
Package postgres provides the PostgreSQL-backed implementation of the document.Repository port, built on native pgx.

Jump to

Keyboard shortcuts

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