spool

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package spool keeps print jobs and sends them to printers: it takes a job and its document, keeps both across restarts, queues the job, sends it to a printer of its queue as print.Print does, follows it until the printer is done, retries what failed for want of the printer, and never prints a job twice after a crash. The states of the jobs are IPP's.

One process owns a spool. Its records and documents are kept in one file through yuruidb (store.go).

Index

Constants

View Source
const (
	// ReasonRetryWait: the printer was not reached; the job is sent again
	// at Due.
	ReasonRetryWait = "bdf-retry-wait"
	// ReasonRetryExhausted: the printer was not reached for as long as the
	// spool retries.
	ReasonRetryExhausted = "bdf-retry-exhausted"
	// ReasonUnsupported: the printer does not support what the ticket
	// asks, and the job is strict.
	ReasonUnsupported = "bdf-unsupported"
	// ReasonDuplicateCheck: after a crash, the printer has more than one
	// job that may be this one; a person decides.
	ReasonDuplicateCheck = "bdf-duplicate-check"
)

Reasons of bdf's own (IPP's job-state-reasons have no keyword for them).

Variables

View Source
var (
	ErrInvalid       = errors.New("spool: invalid request")
	ErrNotFound      = errors.New("spool: no such job")
	ErrNoQueue       = errors.New("spool: no such queue")
	ErrNotAccepting  = errors.New("spool: the queue is not accepting jobs")
	ErrFull          = errors.New("spool: the spool is full")
	ErrTooLarge      = errors.New("spool: the document is too large")
	ErrBadDocument   = errors.New("spool: the document cannot be read")
	ErrUnknownFormat = errors.New("spool: the document is neither a bdf document nor a format the spool converts")
	ErrNotPossible   = errors.New("spool: not possible in the state of the job")
	ErrWrongPassword = errors.New("spool: the password does not open the document")
	// ErrPasswordRequired is returned by a Converter for an input that is
	// encrypted when no password was given.
	ErrPasswordRequired = errors.New("spool: the document is encrypted")
	ErrClosed           = errors.New("spool: closed")
)

Errors of the spool, which a server turns into HTTP statuses.

Functions

func Compact

func Compact(path string) (before, after int64, err error)

Compact rewrites a spool's file without the space that removed jobs and documents left: the file does not shrink by itself. The spool must be closed (a running server holds the file's lock, and Compact fails). It returns the sizes before and after.

This is the one place the spool knows that yuruidb keeps it in bbolt.

Types

type Converted

type Converted struct {
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

Converted is the .bdf made of a document that was not one.

type Converter

type Converter interface {
	// Detect names the format of a document, or says it is unknown; name
	// is its file name, whose extension tells the formats whose content
	// does not (CSV, Markdown).
	Detect(r io.ReaderAt, size int64, name string) (format string, ok bool)
	// Convert makes a document of one in a format Detect named; a
	// password opens an encrypted one (ErrPasswordRequired and
	// ErrWrongPassword tell why it does not). The document of an input
	// that needed the password should be locked with it: the spool keeps
	// it so.
	Convert(ctx context.Context, r io.ReaderAt, size int64, format, name, password string) (*bdf.Document, []string, error)
}

Converter turns documents that are not .bdf into documents: the spool does not depend on the converters, the program that runs it does.

type Document

type Document struct {
	// Name is the file name it came with; Type the media type it was
	// sent as, when the client said.
	Name string `json:"name"`
	Type string `json:"type,omitempty"`
	// Format is "bdf", or the name of the converter's format ("pdf",
	// "xlsx" …) of a document that is converted.
	Format    string `json:"format"`
	Size      int64  `json:"size"`
	SHA256    string `json:"sha256"`
	Encrypted bool   `json:"encrypted,omitempty"`
	// BDF is the document converted to .bdf, once it is.
	BDF *Converted `json:"bdf,omitempty"`
}

Document is the document of a job as it was received.

type Event

type Event struct {
	Job     *Job
	Queue   *QueueInfo
	Printer *PrinterInfo
}

Event tells a change: of a job, of a queue, or of a printer.

type Filter

type Filter struct {
	// Queue and User select the jobs of a queue, of a user.
	Queue, User string
	// Done lists the jobs done within the retention of documents too.
	Done bool
	// After lists the jobs of greater ids; Limit how many (100 by
	// default, at most 1000).
	After int32
	Limit int
}

Filter selects jobs to list.

type Job

type Job struct {
	// ID is a positive integer, as IPP's job-id; UUID is its job-uuid.
	ID   int32  `json:"id"`
	UUID string `json:"uuid"`
	// Queue is the queue the job is in; Name its name (the document's
	// file name, usually); User who submitted it.
	Queue string `json:"queue"`
	Name  string `json:"name"`
	User  string `json:"user"`

	Document Document     `json:"document"`
	Ticket   print.Ticket `json:"ticket"`
	Options  JobOptions   `json:"options"`

	State   ipp.JobState `json:"state"`
	Reasons []string     `json:"reasons,omitempty"`
	Message string       `json:"message,omitempty"`

	// Priority is job-priority, 1 to 100 (50 by default): the higher
	// the sooner.
	Priority int `json:"priority"`
	// HoldUntil is job-hold-until ("indefinite", "night" …) and
	// HoldUntilTime job-hold-until-time.
	HoldUntil     string    `json:"hold-until,omitempty"`
	HoldUntilTime time.Time `json:"hold-until-time,omitzero"`

	// Step is the step to do next, and Due when (a retry, the end of a
	// hold). A job that is done has no step.
	Step Step      `json:"step,omitempty"`
	Due  time.Time `json:"due,omitzero"`
	// Attempts are the times the job was sent; RetrySince is when the
	// printer was first not reached for the current attempt.
	Attempts   int       `json:"attempts"`
	RetrySince time.Time `json:"retry-since,omitzero"`
	// Retries counts the tries since RetrySince, for the delay of the next.
	Retries int `json:"retries,omitempty"`
	// Printer is the printer of the current attempt.
	Printer *PrinterJob `json:"printer,omitempty"`

	Submitted time.Time `json:"submitted"`
	Started   time.Time `json:"started,omitzero"`
	Finished  time.Time `json:"finished,omitzero"`

	// What was sent: sheets (pages with the copies the client made),
	// impressions the printer reported, bytes, the format and media.
	Sheets      int      `json:"sheets,omitempty"`
	Impressions int      `json:"impressions,omitempty"`
	Bytes       int64    `json:"bytes,omitempty"`
	Format      string   `json:"format,omitempty"`
	Media       string   `json:"media,omitempty"`
	Unsupported []string `json:"unsupported,omitempty"`
	Warnings    []string `json:"warnings,omitempty"`

	// DocumentsRemoved is set on a finished job once its documents are
	// removed, after their retention.
	DocumentsRemoved bool `json:"documents-removed,omitempty"`

	// Origin is the upstream job a proxy fetched this one from.
	Origin *Origin `json:"origin,omitempty"`
}

Job is a job of the spool, as it is kept. Its state and reasons are IPP's (job-state, job-state-reasons), with "bdf-" for the reasons IPP has no keyword for.

type JobOptions

type JobOptions struct {
	// Format is "pdf", "pwg-raster" or "" for the queue's.
	Format string `json:"format,omitempty"`
	// View is the id of the view to print; "" the first view of pages.
	View string `json:"view,omitempty"`
	// SkipRoles are the roles of the layers left out.
	SkipRoles []string `json:"skip,omitempty"`
	// Strict makes what the printer does not support an error.
	Strict bool `json:"strict,omitempty"`
	// RasterIfLossy overrides the queue's when set.
	RasterIfLossy *bool `json:"raster-if-lossy,omitempty"`
}

JobOptions are how a job is printed, besides its ticket.

type Limits

type Limits struct {
	// MaxDocument is the size of a document: 256 MiB by default.
	MaxDocument int64
	// MaxJobs and MaxBytes bound the jobs not done and their documents:
	// 10,000 and 10 GiB by default. Beyond them a job is refused (ErrFull).
	MaxJobs  int
	MaxBytes int64
	// RetryFor is how long a job is sent again to a printer that is not
	// reached before it is aborted: 24 hours by default.
	RetryFor time.Duration
	// Renders is how many jobs are converted or drawn at once: the
	// number of CPUs by default.
	Renders int
	// MaxImpressions is print.Options'.
	MaxImpressions int
}

Limits bound what the spool takes.

type Options

type Options struct {
	// Path is the file of the spool.
	Path string
	// Timeout is how long Open waits for the file's lock: 1 second by
	// default. Another process holding it is an error.
	Timeout time.Duration
	Queues  []Queue
	// Printers are the printers the queues name.
	Printers []Printer
	// Converter converts documents that are not .bdf; nil takes .bdf
	// only.
	Converter Converter
	Limits    Limits
	Retention Retention
	// TempDir holds documents while they arrive: os.TempDir by default.
	TempDir string
	// FontFS, FontDirs and NoSystemFonts are print.Options' and the
	// converter's.
	FontFS        fs.FS
	FontDirs      []string
	NoSystemFonts bool
	// Now is the clock; time.Now by default.
	Now func() time.Time
	// Log receives what happens to jobs and printers; nothing by default.
	Log *slog.Logger
}

Options are a spool's.

type Origin

type Origin struct {
	Upstream string `json:"upstream"`
	JobID    int32  `json:"job-id"`
	UUID     string `json:"uuid"`
}

Origin is where a job a proxy fetched comes from: the upstream (the name of its configuration), the job's id and uuid there.

type Printer

type Printer struct {
	Name   string
	Client *ipp.Client
	Raw    *raw.Printer
	// Proxy makes a printer that proxies fetch jobs from (proxy.go), with
	// neither Client nor Raw.
	Proxy bool
	// Format is the language of a printer of labels, receipts or forms
	// (print/pdl) that an IPP Client passes on as it is (a raw queue of
	// CUPS): every job is sent in it. Profile is the printer that the
	// language is written for, of a Client or of a Raw printer (nil for
	// the profile of the Raw printer's URL).
	Format  string
	Profile *pdl.Profile
}

Printer is a printer jobs are sent to: an IPP printer (Client), or one of 9100 or LPD (Raw), which tells nothing of its jobs. A job sent to the latter is done once the printer has it; one that the printer may have begun to print when the spool stopped (or the connection broke) is held for a person (bdf-duplicate-check), as it is not known whether it was printed.

type PrinterInfo

type PrinterInfo struct {
	Name      string   `json:"name"`
	URL       string   `json:"url"`
	Up        bool     `json:"up"`
	State     string   `json:"state,omitempty"`
	Reasons   []string `json:"reasons,omitempty"`
	Message   string   `json:"message,omitempty"`
	Accepting bool     `json:"accepting"`
	MakeModel string   `json:"make-and-model,omitempty"`
	// Checked is when the printer was last asked, and Error why it did
	// not answer.
	Checked time.Time `json:"checked,omitzero"`
	Error   string    `json:"error,omitempty"`
	// Jobs are the jobs sent to it and not done.
	Jobs int `json:"jobs"`
}

PrinterInfo is a printer and what it said last.

type PrinterJob

type PrinterJob struct {
	Name string `json:"name"`
	URL  string `json:"url"`
	// AttemptStarted is when the attempt began, before Create-Job.
	AttemptStarted time.Time `json:"attempt-started"`
	JobID          int32     `json:"job-id,omitempty"`
	JobURI         string    `json:"job-uri,omitempty"`
	// Begun says that a raw printer may have begun to print the job: what
	// it may print was being sent.
	Begun bool `json:"begun,omitempty"`
	Sent  bool `json:"sent,omitempty"`
	// Device is the output-device-uuid of the proxy a job of a printer
	// of proxies is bound to.
	Device string `json:"device,omitempty"`
}

PrinterJob is the job of an attempt at a printer. JobID is set as soon as the printer answers Create-Job, before the document is sent, and Sent once the printer has the whole document: after a crash they tell whether the printer has the job already.

type Queue

type Queue struct {
	Name string
	// Printers are the names of the printers, in order; more than one
	// makes a class.
	Printers []string
	// Policy is "any" (the first printer free) or "failover" (the first
	// printer that is up, in order); "" is "failover".
	Policy string
	// Defaults are the ticket's defaults: a job's ticket asks over them.
	Defaults print.Ticket
	// Format and RasterIfLossy are print.Options'.
	Format        string
	RasterIfLossy bool
	// MaxInflight is how many jobs of the queue a printer is given before
	// the first is done: 2 by default, so that the next is there when
	// the first is printed.
	MaxInflight int
}

Queue is a queue of jobs and the printers its jobs are sent to.

type QueueInfo

type QueueInfo struct {
	Name     string   `json:"name"`
	Printers []string `json:"printers"`
	Policy   string   `json:"policy"`
	// Paused queues take jobs and do not send them; Rejecting ones do
	// not take jobs.
	Paused    bool `json:"paused"`
	Rejecting bool `json:"rejecting"`
	// Jobs counts the jobs not done, by state.
	Jobs map[string]int `json:"jobs"`
}

QueueInfo is a queue and how many of its jobs are in each state.

type QueueState

type QueueState struct {
	Queue, State string
}

QueueState is a queue and a job state.

type Retention

type Retention struct {
	// Documents of the jobs done: 7 days by default.
	Documents time.Duration
	// Records of the jobs done, which are the accounting: 400 days by
	// default.
	Records time.Duration
}

Retention is how long what is done is kept.

type Spool

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

Spool is a spool, open.

func Open

func Open(ctx context.Context, o Options) (*Spool, error)

Open opens a spool, recovering what a crash left: documents that were arriving, jobs recorded as done but not removed, and jobs that were at a printer, which are checked against the printer before anything is sent again (Start sends them).

func (*Spool) AcceptQueue

func (s *Spool) AcceptQueue(ctx context.Context, name string) (QueueInfo, error)

func (*Spool) Accounting

func (s *Spool) Accounting(ctx context.Context, from, to time.Time, format string, w io.Writer) error

Accounting writes the jobs done between from and to (by when they were done; a zero time does not bound) as JSON Lines ("jsonl") or CSV ("csv"), oldest first: who printed what, where, and how much.

func (*Spool) AcknowledgeDocument

func (s *Spool) AcknowledgeDocument(ctx context.Context, id int32, printer, device string) (Job, error)

AcknowledgeDocument records that the proxy of device has the document of a job it acknowledged: the job waits for its reports.

func (*Spool) AcknowledgeJob

func (s *Spool) AcknowledgeJob(ctx context.Context, id int32, printer, device string) (Job, error)

AcknowledgeJob binds a fetchable job to the proxy of device: no other proxy is given it.

func (*Spool) Backup

func (s *Spool) Backup(ctx context.Context, w io.Writer) error

Backup writes a consistent copy of the spool's file.

func (*Spool) Cancel

func (s *Spool) Cancel(ctx context.Context, id int32, reason string) (Job, error)

Cancel cancels a job. A job at a printer is canceled there too.

func (*Spool) Close

func (s *Spool) Close() error

Close stops the spool as Shutdown does, giving sends 30 seconds.

func (*Spool) Collect

func (s *Spool) Collect(ctx context.Context) error

Collect removes what the retention no longer keeps: the documents of the jobs done after Retention.Documents, the records of the jobs done after Retention.Records, and documents of no job (a crash while one arrived). The runner calls it every hour.

func (*Spool) Document

func (s *Spool) Document(ctx context.Context, id int32) (*bdf.Document, error)

Document opens the document of a job as a .bdf (the one received, or the one converted), unlocked with the password the spool holds.

func (*Spool) Fetchable

func (s *Spool) Fetchable(printer, device string) []Job

Fetchable are the jobs the proxy of device may fetch for a printer: the pending jobs offered to it and bound to no proxy, and those bound to this one whose document it has not acknowledged (it fetches them again after it stopped).

func (*Spool) FindOrigin

func (s *Spool) FindOrigin(ctx context.Context, upstream, uuid string) (Job, bool)

FindOrigin finds the job, done or not, that came from an upstream's job of a uuid: a proxy does not take a job twice.

func (*Spool) Get

func (s *Spool) Get(ctx context.Context, id int32) (Job, error)

Get returns a job, done or not.

func (*Spool) Hold

func (s *Spool) Hold(ctx context.Context, id int32) (Job, error)

Hold holds a job that is pending until it is released.

func (*Spool) IsProxy

func (s *Spool) IsProxy(printer string) bool

IsProxy tells a printer of proxies.

func (*Spool) List

func (s *Spool) List(f Filter) []Job

List returns jobs in the order of their ids.

func (*Spool) Move

func (s *Spool) Move(ctx context.Context, id int32, queue string) (Job, error)

Move moves a job that is not processed yet to another queue.

func (*Spool) OpenBDF

func (s *Spool) OpenBDF(ctx context.Context, id int32) (io.ReadCloser, int64, error)

OpenBDF opens the .bdf of a job as it is kept (locked when it was): the one received, or the one converted. The caller closes it.

func (*Spool) Origins

func (s *Spool) Origins(upstream string) []Job

Origins are the jobs that came from an upstream, done within the retention of documents or not: of an upstream job taken more than once (it was retried there), the last taken.

func (*Spool) Password

func (s *Spool) Password(id int32) string

Password is the password the spool holds of a job's document, "" when none.

func (*Spool) PauseQueue

func (s *Spool) PauseQueue(ctx context.Context, name string) (QueueInfo, error)

PauseQueue stops sending the jobs of a queue (it still takes them); ResumeQueue sends them again.

func (*Spool) PrinterCapabilities

func (s *Spool) PrinterCapabilities(name string) (*ipp.Printer, error)

PrinterCapabilities returns what a printer said last it supports, or nil before it answered.

func (*Spool) Printers

func (s *Spool) Printers() []PrinterInfo

Printers returns the printers, by name.

func (*Spool) ProxyGone

func (s *Spool) ProxyGone(printer, device string)

ProxyGone records that a proxy stopped (Deregister-Output-Device).

func (*Spool) ProxyJobs

func (s *Spool) ProxyJobs(printer, device string) []Job

ProxyJobs are the jobs bound to the proxy of device that are not done here: those it should have.

func (*Spool) ProxyLost

func (s *Spool) ProxyLost(ctx context.Context, id int32, printer, device string) (Job, error)

ProxyLost ends a job the proxy of device had the document of and no longer knows (it lost its spool): aborted, for a person to retry.

func (*Spool) ProxyReport

func (s *Spool) ProxyReport(ctx context.Context, id int32, printer, device string, st ipp.JobState, reasons []string, impressions int, message string) (Job, error)

ProxyReport records what the proxy of device reports of a job: its state at the proxy, the reasons, the impressions, a message. The job ends when the proxy's does. A job already ended here (canceled) is returned as it is, with ErrNotPossible, for the proxy to end its own.

func (*Spool) ProxySeen

func (s *Spool) ProxySeen(printer, device string, caps *ipp.Printer) error

ProxySeen records what a proxy reports of the printer behind it (its state and capabilities): the printer of proxies is up while the proxies report, for proxyStale.

func (*Spool) Queue

func (s *Spool) Queue(name string) (QueueInfo, error)

Queue returns a queue.

func (*Spool) Queues

func (s *Spool) Queues() []QueueInfo

Queues returns the queues, by name.

func (*Spool) Receive

func (s *Spool) Receive(ctx context.Context, r io.Reader) (*Upload, error)

Receive reads a document to a temporary file (Options.TempDir), measuring it, for Submission.Upload.

func (*Spool) RejectQueue

func (s *Spool) RejectQueue(ctx context.Context, name string) (QueueInfo, error)

RejectQueue stops taking jobs in a queue; AcceptQueue takes them again.

func (*Spool) Release

func (s *Spool) Release(ctx context.Context, id int32, password string) (Job, error)

Release releases a held job; a password opens its document when it waits for one.

func (*Spool) ReserveID

func (s *Spool) ReserveID(ctx context.Context) (int32, error)

ReserveID takes the id of a job to submit later (Submission.ID): IPP's Create-Job tells a job's id before its document arrives. An id that is not submitted after all is skipped.

func (*Spool) ResumeQueue

func (s *Spool) ResumeQueue(ctx context.Context, name string) (QueueInfo, error)

func (*Spool) Retry

func (s *Spool) Retry(ctx context.Context, id int32) (Job, error)

Retry queues again a job that was canceled or aborted, as a new attempt.

func (*Spool) SetPassword

func (s *Spool) SetPassword(ctx context.Context, id int32, password string) (Job, error)

SetPassword gives the password of an encrypted document: a job waiting for it is queued.

func (*Spool) SetPriority

func (s *Spool) SetPriority(ctx context.Context, id int32, priority int) (Job, error)

SetPriority changes the priority of a job not processed yet.

func (*Spool) Shutdown

func (s *Spool) Shutdown(grace time.Duration) error

Shutdown stops the spool: no step starts, the steps that only wait stop at once, and the documents being sent to printers are given grace to finish (a send cut is put right when the spool opens again). Then the file is closed.

func (*Spool) Start

func (s *Spool) Start()

Start runs the spool: a watcher per printer, and the loop that converts documents, sends jobs to their printers and follows them. Jobs that were at a printer when the spool last stopped are checked against the printer first. Close stops it.

func (*Spool) Stats

func (s *Spool) Stats() Stats

Stats returns the spool's counts.

func (*Spool) Submit

func (s *Spool) Submit(ctx context.Context, sub Submission) (Job, error)

Submit takes a job: it stores its document and records the job, which is then queued (or held). The document is read to its end before the job is recorded.

func (*Spool) Subscribe

func (s *Spool) Subscribe(buffer int) (<-chan Event, func())

Subscribe returns a channel of the changes of jobs and queues, and a function that ends the subscription. Changes are dropped when the channel is full.

func (*Spool) TrustStore

func (s *Spool) TrustStore() *ipp.TrustStore

TrustStore keeps the fingerprints of the printers' certificates in the spool, for the printers' clients.

type Stats

type Stats struct {
	// Done counts the jobs done, by queue and state.
	Done map[QueueState]int64
	// Sheets counts the sheets of the jobs done, by queue.
	Sheets map[string]int64
	// SentBytes counts the bytes printers took, and Retries the jobs put
	// back because a printer did not take them, by printer.
	SentBytes map[string]int64
	Retries   map[string]int64
	// Bytes is the size of the documents of the jobs not done; FileSize
	// the size of the spool's file.
	Bytes    int64
	FileSize int64
}

Stats count what the spool did since it opened, and what it holds: a server's metrics.

type Step

type Step string

Step is the part of a job's processing it is at: each is short and can be started again after a crash.

const (
	// StepConvert turns a document that is not a .bdf into one.
	StepConvert Step = "convert"
	// StepSend makes the job at a printer and sends the document.
	StepSend Step = "send"
	// StepWatch follows the job at the printer until it is done.
	StepWatch Step = "watch"
)

Steps.

const (
	// StepFetch waits for a proxy to fetch the job.
	StepFetch Step = "fetch"
	// StepRemote waits for the proxy that has the job to report it.
	StepRemote Step = "remote"
)

Steps of the jobs of proxies.

type Submission

type Submission struct {
	// ID is an id ReserveID gave, for a job whose id was told before its
	// document arrived (IPP's Create-Job); 0 takes the next. UUID is the
	// job-uuid told with it; "" makes one.
	ID    int32
	UUID  string
	Queue string
	// Name is the document's file name; User who submits it.
	Name, User string
	// Type is the media type the document was sent as
	// ("application/pdf"), when the client said: the formats whose
	// content does not tell them (text/plain, text/csv) are known by it.
	Type string
	// Document is read to its end by Submit; or Upload, a document
	// received before (Receive), which Submit takes.
	Document io.Reader
	Upload   *Upload
	Ticket   print.Ticket
	Options  JobOptions
	// Priority is 1 to 100; 0 is 50.
	Priority int
	// HoldUntil and HoldUntilTime hold the job (job-hold-until).
	HoldUntil     string
	HoldUntilTime time.Time
	// Password opens an encrypted document. It is kept in memory only:
	// after a restart such a job waits for it again (job-password-wait).
	Password string
	// Origin is the upstream job a proxy fetched this one from.
	Origin *Origin
}

Submission is a job to submit.

type Upload

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

Upload is a document received before its job is submitted: a server reads the document of a request before the fields that follow it.

func (*Upload) Discard

func (u *Upload) Discard()

Discard drops a document no job took.

func (*Upload) Size

func (u *Upload) Size() int64

Size is the document's size.

Jump to

Keyboard shortcuts

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