client

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: 15 Imported by: 0

Documentation

Overview

Package client talks to a print server (bdf printd) over its HTTP API: it submits documents, follows and changes jobs, and reads the queues, the printers and the accounting. It depends on nothing of bdf: its types have the shape of the API's JSON.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsCode

func IsCode(err error, code string) bool

IsCode tells an error the server answered with a code.

Types

type Capabilities

type Capabilities struct {
	Formats          []string `json:"document-format-supported,omitempty"`
	Media            []string `json:"media-supported,omitempty"`
	MediaReady       []string `json:"media-ready,omitempty"`
	MediaDefault     string   `json:"media-default,omitempty"`
	MediaSources     []string `json:"media-source-supported,omitempty"`
	MediaTypes       []string `json:"media-type-supported,omitempty"`
	Sides            []string `json:"sides-supported,omitempty"`
	SidesDefault     string   `json:"sides-default,omitempty"`
	ColorModes       []string `json:"print-color-mode-supported,omitempty"`
	ColorModeDefault string   `json:"print-color-mode-default,omitempty"`
	Qualities        []int32  `json:"print-quality-supported,omitempty"`
	Finishings       []int32  `json:"finishings-supported,omitempty"`
	OutputBins       []string `json:"output-bin-supported,omitempty"`
	CopiesMax        int32    `json:"copies-max,omitempty"`
	Location         string   `json:"printer-location,omitempty"`
	Info             string   `json:"printer-info,omitempty"`
}

Capabilities are what a printer supports, with IPP's names.

type Client

type Client struct {
	// URL is the server's: http://127.0.0.1:8640 by default.
	URL string
	// Token is the bearer token; "" sends none (a server without tokens).
	Token string
	// User names the user of the jobs (X-BDF-User): a server takes it
	// from a token that may act for others, or when it has no tokens.
	User string
	// HTTP is the HTTP client; http.DefaultClient by default.
	HTTP *http.Client
}

Client is a client of a print server.

func (*Client) Accounting

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

Accounting writes the jobs done from to to (zero times do not bound; to excludes) as "jsonl" or "csv".

func (*Client) Backup

func (c *Client) Backup(ctx context.Context, w io.Writer) error

Backup writes a copy of the server's spool.db.

func (*Client) Cancel

func (c *Client) Cancel(ctx context.Context, id int32) (*Job, error)

Cancel cancels a job, at its printer too.

func (*Client) Events

func (c *Client) Events(ctx context.Context, job int32, f func(Event) error) error

Events calls f with the changes the server tells until ctx ends, f returns an error, or the stream ends (io.EOF); job (0: all) follows one job. Changes the server could not send in time are not told: a client that comes back reads the state again.

func (*Client) Hold

func (c *Client) Hold(ctx context.Context, id int32) (*Job, error)

Hold holds a job that is not sent yet.

func (*Client) Job

func (c *Client) Job(ctx context.Context, id int32) (*Job, error)

Job returns a job.

func (*Client) Jobs

func (c *Client) Jobs(ctx context.Context, f JobFilter) (*JobList, error)

Jobs lists a page of jobs.

func (*Client) Move

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

Move moves a job not sent yet to another queue.

func (*Client) Printer

func (c *Client) Printer(ctx context.Context, name string) (*Printer, error)

Printer returns a printer, with what it supports.

func (*Client) Printers

func (c *Client) Printers(ctx context.Context) ([]Printer, error)

Printers returns the printers.

func (*Client) Queue

func (c *Client) Queue(ctx context.Context, name string) (*Queue, error)

Queue returns a queue.

func (*Client) QueueOp

func (c *Client) QueueOp(ctx context.Context, name, op string) (*Queue, error)

QueueOp pauses ("pause"), resumes ("resume"), rejects ("reject") or accepts ("accept") a queue.

func (*Client) Queues

func (c *Client) Queues(ctx context.Context) ([]Queue, error)

Queues returns the queues.

func (*Client) Release

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

Release releases a held job; a password opens an encrypted document that waits for one.

func (*Client) Retry

func (c *Client) Retry(ctx context.Context, id int32) (*Job, error)

Retry sends again a job that was aborted or canceled.

func (*Client) SetPassword

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

SetPassword gives the password of an encrypted document.

func (*Client) SetPriority

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

SetPriority changes a job's priority (1 to 100).

func (*Client) Submit

func (c *Client) Submit(ctx context.Context, sub Submission) (*Job, error)

Submit submits a job. The document is streamed after the other fields.

func (*Client) Wait

func (c *Client) Wait(ctx context.Context, id int32, changed func(*Job)) (*Job, error)

Wait follows a job until it is done and returns it; each change of its state, reasons or printer goes to changed (nil: none). It follows the server's events, and asks for the job when the stream opens, every while, and when the stream is lost, so that no change is missed.

type Converted

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

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

type Document

type Document struct {
	Name string `json:"name"`
	// Type is the media type it was sent as, when the client said.
	Type      string     `json:"type,omitempty"`
	Format    string     `json:"format"`
	Size      int64      `json:"size"`
	SHA256    string     `json:"sha256"`
	Encrypted bool       `json:"encrypted,omitempty"`
	BDF       *Converted `json:"bdf,omitempty"`
}

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

type Error

type Error struct {
	Status  int    // the HTTP status
	Code    string // "not-found", "not-accepting", "full" …
	Message string
}

Error is an error the server answered.

func (*Error) Error

func (e *Error) Error() string

type Event

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

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

type Job

type Job struct {
	ID       int32           `json:"id"`
	UUID     string          `json:"uuid"`
	Queue    string          `json:"queue"`
	Name     string          `json:"name"`
	User     string          `json:"user"`
	Document Document        `json:"document"`
	Ticket   json.RawMessage `json:"ticket,omitempty"`
	Options  JobOptions      `json:"options"`

	// State is pending, pending-held, processing, processing-stopped,
	// canceled, aborted or completed.
	State   string   `json:"state"`
	Reasons []string `json:"reasons,omitempty"`
	Message string   `json:"message,omitempty"`

	Priority      int       `json:"priority"`
	HoldUntil     string    `json:"hold-until,omitempty"`
	HoldUntilTime time.Time `json:"hold-until-time,omitzero"`

	// Step is what the server does next (convert, send, watch), and Due
	// when (a retry, the end of a hold).
	Step       string      `json:"step,omitempty"`
	Due        time.Time   `json:"due,omitzero"`
	Attempts   int         `json:"attempts"`
	RetrySince time.Time   `json:"retry-since,omitzero"`
	Retries    int         `json:"retries,omitempty"`
	Printer    *PrinterJob `json:"printer,omitempty"`

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

	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 bool `json:"documents-removed,omitempty"`
	// Origin is the job of an upstream server a proxy fetched this one
	// from.
	Origin *Origin `json:"origin,omitempty"`
}

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

func (*Job) Done

func (j *Job) Done() bool

Done tells a job that is canceled, aborted or completed.

type JobFilter

type JobFilter struct {
	Queue, User string
	// State is "" (the jobs not done), "all" (with those done within the
	// server's retention of documents) or a job-state.
	State string
	// After lists the jobs of greater ids; Limit how many (100 by
	// default, at most 1000).
	After int32
	Limit int
}

JobFilter selects jobs to list.

type JobList

type JobList struct {
	Jobs []Job `json:"jobs"`
	Next int32 `json:"next,omitempty"`
}

JobList is a page of jobs; Next is the After of the next page, when there may be one.

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 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 job's id and uuid there.

type Printer

type Printer 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   time.Time `json:"checked,omitzero"`
	Error     string    `json:"error,omitempty"`
	// Jobs are the jobs sent to it and not done.
	Jobs int `json:"jobs"`
	// Capabilities are what it supports (Client.Printer only).
	Capabilities *Capabilities `json:"capabilities,omitempty"`
}

Printer is a printer of the server and what it said last.

type PrinterJob

type PrinterJob struct {
	Name           string    `json:"name"`
	URL            string    `json:"url"`
	AttemptStarted time.Time `json:"attempt-started"`
	JobID          int32     `json:"job-id,omitempty"`
	JobURI         string    `json:"job-uri,omitempty"`
	// Begun says that a printer of 9100 or LPD may have begun to print
	// the job.
	Begun bool `json:"begun,omitempty"`
	Sent  bool `json:"sent,omitempty"`
	// Device is the output-device-uuid of the proxy that fetched the job,
	// of a printer of proxies.
	Device string `json:"device,omitempty"`
}

PrinterJob is the job of an attempt at a printer.

type Queue

type Queue 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"`
}

Queue is a queue of the server.

type Submission

type Submission struct {
	Queue string
	// Name is the document's file name, which the server's converter
	// reads the format of some inputs from (.csv, .md).
	Name     string
	Document io.Reader
	// Ticket is what to print: a print.Ticket, or anything that is the
	// JSON of one ({"copies": 2, "sides": "two-sided-long-edge"}).
	Ticket   any
	Options  *JobOptions
	Password string
	// Priority is 1 to 100; 0 is the server's (50).
	Priority      int
	HoldUntil     string
	HoldUntilTime time.Time
}

Submission is a job to submit.

Jump to

Keyboard shortcuts

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