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
- Variables
- func Compact(path string) (before, after int64, err error)
- type Converted
- type Converter
- type Document
- type Event
- type Filter
- type Job
- type JobOptions
- type Limits
- type Options
- type Origin
- type Printer
- type PrinterInfo
- type PrinterJob
- type Queue
- type QueueInfo
- type QueueState
- type Retention
- type Spool
- func (s *Spool) AcceptQueue(ctx context.Context, name string) (QueueInfo, error)
- func (s *Spool) Accounting(ctx context.Context, from, to time.Time, format string, w io.Writer) error
- func (s *Spool) AcknowledgeDocument(ctx context.Context, id int32, printer, device string) (Job, error)
- func (s *Spool) AcknowledgeJob(ctx context.Context, id int32, printer, device string) (Job, error)
- func (s *Spool) Backup(ctx context.Context, w io.Writer) error
- func (s *Spool) Cancel(ctx context.Context, id int32, reason string) (Job, error)
- func (s *Spool) Close() error
- func (s *Spool) Collect(ctx context.Context) error
- func (s *Spool) Document(ctx context.Context, id int32) (*bdf.Document, error)
- func (s *Spool) Fetchable(printer, device string) []Job
- func (s *Spool) FindOrigin(ctx context.Context, upstream, uuid string) (Job, bool)
- func (s *Spool) Get(ctx context.Context, id int32) (Job, error)
- func (s *Spool) Hold(ctx context.Context, id int32) (Job, error)
- func (s *Spool) IsProxy(printer string) bool
- func (s *Spool) List(f Filter) []Job
- func (s *Spool) Move(ctx context.Context, id int32, queue string) (Job, error)
- func (s *Spool) OpenBDF(ctx context.Context, id int32) (io.ReadCloser, int64, error)
- func (s *Spool) Origins(upstream string) []Job
- func (s *Spool) Password(id int32) string
- func (s *Spool) PauseQueue(ctx context.Context, name string) (QueueInfo, error)
- func (s *Spool) PrinterCapabilities(name string) (*ipp.Printer, error)
- func (s *Spool) Printers() []PrinterInfo
- func (s *Spool) ProxyGone(printer, device string)
- func (s *Spool) ProxyJobs(printer, device string) []Job
- func (s *Spool) ProxyLost(ctx context.Context, id int32, printer, device string) (Job, error)
- func (s *Spool) ProxyReport(ctx context.Context, id int32, printer, device string, st ipp.JobState, ...) (Job, error)
- func (s *Spool) ProxySeen(printer, device string, caps *ipp.Printer) error
- func (s *Spool) Queue(name string) (QueueInfo, error)
- func (s *Spool) Queues() []QueueInfo
- func (s *Spool) Receive(ctx context.Context, r io.Reader) (*Upload, error)
- func (s *Spool) RejectQueue(ctx context.Context, name string) (QueueInfo, error)
- func (s *Spool) Release(ctx context.Context, id int32, password string) (Job, error)
- func (s *Spool) ReserveID(ctx context.Context) (int32, error)
- func (s *Spool) ResumeQueue(ctx context.Context, name string) (QueueInfo, error)
- func (s *Spool) Retry(ctx context.Context, id int32) (Job, error)
- func (s *Spool) SetPassword(ctx context.Context, id int32, password string) (Job, error)
- func (s *Spool) SetPriority(ctx context.Context, id int32, priority int) (Job, error)
- func (s *Spool) Shutdown(grace time.Duration) error
- func (s *Spool) Start()
- func (s *Spool) Stats() Stats
- func (s *Spool) Submit(ctx context.Context, sub Submission) (Job, error)
- func (s *Spool) Subscribe(buffer int) (<-chan Event, func())
- func (s *Spool) TrustStore() *ipp.TrustStore
- type Stats
- type Step
- type Submission
- type Upload
Constants ¶
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 ¶
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 ¶
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 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 ¶
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 (*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 ¶
AcknowledgeJob binds a fetchable job to the proxy of device: no other proxy is given it.
func (*Spool) Collect ¶
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 ¶
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 ¶
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 ¶
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) OpenBDF ¶
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 ¶
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 ¶
Password is the password the spool holds of a job's document, "" when none.
func (*Spool) PauseQueue ¶
PauseQueue stops sending the jobs of a queue (it still takes them); ResumeQueue sends them again.
func (*Spool) PrinterCapabilities ¶
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) ProxyJobs ¶
ProxyJobs are the jobs bound to the proxy of device that are not done here: those it should have.
func (*Spool) ProxyLost ¶
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 ¶
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) Receive ¶
Receive reads a document to a temporary file (Options.TempDir), measuring it, for Submission.Upload.
func (*Spool) RejectQueue ¶
RejectQueue stops taking jobs in a queue; AcceptQueue takes them again.
func (*Spool) Release ¶
Release releases a held job; a password opens its document when it waits for one.
func (*Spool) ReserveID ¶
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 (*Spool) SetPassword ¶
SetPassword gives the password of an encrypted document: a job waiting for it is queued.
func (*Spool) SetPriority ¶
SetPriority changes the priority of a job not processed yet.
func (*Spool) Shutdown ¶
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) Submit ¶
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 ¶
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.
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.