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
- Variables
- type Config
- type Document
- type GenerateInput
- type Renderer
- type Repository
- type Service
- func (s *Service) ExistsForCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID, templateName string) (bool, error)
- func (s *Service) FindByVerificationKey(ctx context.Context, db pgxtx.DBTX, key string) (*Document, error)
- func (s *Service) Generate(ctx context.Context, db pgxtx.DBTX, in GenerateInput) (*Document, error)
- func (s *Service) Get(ctx context.Context, db pgxtx.DBTX, id uuid.UUID) (*Document, error)
- func (s *Service) ListByCase(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]Document, error)
- type Signer
- type Template
Constants ¶
const ContentType = "application/pdf"
ContentType is the MIME type every generated document is stored with.
const DefaultCleanupTimeout = 10 * time.Second
DefaultCleanupTimeout is the Config.CleanupTimeout used when it is zero.
const DefaultKeyPrefix = "documents"
DefaultKeyPrefix is the storage key prefix used when Config.KeyPrefix is empty.
Variables ¶
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 ¶
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 ¶
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.
type Signer ¶
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 ¶
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.
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. |