server

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

Documentation

Overview

Package server is the print server: a spool (print/spool) of the queues and printers of a configuration file, its HTTP API (/api/v1), the changes as Server-Sent Events, /metrics, and a page of its state. bdf printd runs it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AirPrintProfile

func AirPrintProfile(cfg *Config, host string, port int) ([]byte, error)

AirPrintProfile is a configuration profile (.mobileconfig) that adds the IPP printers to iPhones and iPads that do not see them with mDNS (on another subnet): an AirPrint payload of each queue (the address, its path, the port, TLS), and the server's certificate as a root to trust when the server signed it itself. An MDM sends it, or a person opens it in Safari (the page of the printers links it). host is the name or the address the devices reach the server at; port the IPP server's.

func ZoneRecords

func ZoneRecords(cfg *Config, domain string, port int, caps map[string]*ipp.Printer) (string, error)

ZoneRecords are the records of the queues for a DNS zone (RFC 6763 §11, wide-area DNS-SD), in the zone file's format: clients of other subnets find the printers in the domain, as they find them with mDNS on theirs. The host is the IPP server's (ipp.host), a name of the zone; caps give the queues' printers' capabilities (CheckPrinters), nil when unknown.

Types

type Config

type Config struct {
	// Listen is the address of the HTTP API: 127.0.0.1:8640 by default.
	Listen string `yaml:"listen"`
	// Spool is the spool's file: spool.db next to the configuration
	// file by default.
	Spool string `yaml:"spool"`
	// User is the requesting-user-name sent to the printers: "bdf" by
	// default.
	User string `yaml:"user"`
	// TLS serves HTTPS; it is required when Listen is not a loopback
	// address, unless Insecure.
	TLS      *TLSConfig `yaml:"tls"`
	Insecure bool       `yaml:"insecure"`
	// Tokens are who may use the API. None on a loopback address lets
	// anyone of the machine use it.
	Tokens    []TokenConfig            `yaml:"tokens"`
	Printers  map[string]PrinterConfig `yaml:"printers"`
	Queues    map[string]QueueConfig   `yaml:"queues"`
	Retention RetentionConfig          `yaml:"retention"`
	Limits    LimitsConfig             `yaml:"limits"`
	Fonts     FontsConfig              `yaml:"fonts"`
	// TempDir holds documents while they arrive.
	TempDir string `yaml:"temp-dir"`
	// IPP shows the queues as IPP printers, which the systems add without
	// a driver (IPP Everywhere, AirPrint, Mopria).
	IPP *IPPConfig `yaml:"ipp"`
	// Upstreams are the servers this one fetches jobs from, as a proxy
	// of a branch (IPP INFRA): each into a queue of this server.
	Upstreams map[string]UpstreamConfig `yaml:"upstreams"`
	// contains filtered or unexported fields
}

Config is the configuration of a server, as its YAML file has it.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads a configuration file, with its secrets, and checks it.

func ParseConfig

func ParseConfig(b []byte) (*Config, error)

ParseConfig reads a configuration from YAML and checks it; paths are relative to the working directory.

type Duration

type Duration time.Duration

Duration reads "90s", "24h" and "7d".

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(n *yaml.Node) error

type FontsConfig

type FontsConfig struct {
	Dirs     []string `yaml:"dirs"`
	NoSystem bool     `yaml:"no-system"`
}

FontsConfig finds the fonts of documents that name them.

type IPPConfig

type IPPConfig struct {
	// Listen is the address: ":8631" by default.
	Listen string `yaml:"listen"`
	// Host is the name of the server in the printers' URIs, the
	// certificate and DNS-SD: the machine's name, in .local, by default.
	Host string `yaml:"host"`
	// Auth is "none" (anyone of the network prints, under the
	// requesting-user-name it gives) or "basic" (a token's name and
	// secret): basic when there are tokens.
	Auth string `yaml:"auth"`
	// RequireTLS refuses ipp (HTTP 426): only ipps. It is so with basic.
	RequireTLS bool `yaml:"require-tls"`
	// TLS is the certificate of ipps; without it the server makes one,
	// signed by itself, kept next to the spool (ipp-tls.pem).
	TLS *TLSConfig `yaml:"tls"`
	// Queues are the queues shown; all by default. Default is also shown
	// at /ipp/print.
	Queues  []string `yaml:"queues"`
	Default string   `yaml:"default"`
	// Location, Organization and OrganizationalUnit describe the
	// printers (printer-location …), a queue's location over Location.
	Location           string `yaml:"location"`
	Organization       string `yaml:"organization"`
	OrganizationalUnit string `yaml:"organizational-unit"`
	// DNSSD advertises the printers on the local links (mDNS): true by
	// default.
	DNSSD *bool `yaml:"dns-sd"`
}

IPPConfig is the IPP server of the queues: a printer of each at /ipp/print/<queue>, ipp and ipps on one port, advertised with DNS-SD.

type LimitsConfig

type LimitsConfig struct {
	MaxDocument    Size     `yaml:"max-document"`
	MaxJobs        int      `yaml:"max-jobs"`
	MaxBytes       Size     `yaml:"max-bytes"`
	MaxImpressions int      `yaml:"max-impressions"`
	Renders        int      `yaml:"renders"`
	RetryFor       Duration `yaml:"retry-for"`
	// Uploads and Events bound the submissions and the event streams at
	// once: 8 and 64 by default.
	Uploads int `yaml:"uploads"`
	Events  int `yaml:"events"`
}

LimitsConfig bounds what the server takes.

type Options

type Options struct {
	// Converter converts the documents that are not .bdf; nil takes .bdf
	// only.
	Converter spool.Converter
	// FontFS adds fonts to the configuration's.
	FontFS fs.FS
	// Log receives what happens; nothing by default.
	Log *slog.Logger
	// Grace is how long Serve lets the documents being sent finish when
	// it stops: 30 seconds by default.
	Grace time.Duration
	// Now is the clock; time.Now by default.
	Now func() time.Time
	// IPPListener is the listener of the IPP server (Config.IPP) for
	// Serve; nil listens on the configuration's address.
	IPPListener net.Listener
}

Options are what a server takes besides its configuration.

type PrinterCheck

type PrinterCheck struct {
	Name string
	// URL is the printer's, without a user and password.
	URL     string
	Printer *ipp.Printer
	Err     error
}

PrinterCheck is what a printer of a configuration answered.

func CheckPrinters

func CheckPrinters(ctx context.Context, cfg *Config) []PrinterCheck

CheckPrinters asks each printer of a configuration what it supports, without opening the spool. The certificate of an ipps printer is checked against its pinned fingerprint; one not pinned is taken as the first one seen (the fingerprints the spool recorded are not read).

type PrinterConfig

type PrinterConfig struct {
	// Proxy makes a printer that proxies of branches fetch the jobs of
	// (IPP INFRA), with no URL: the bdf printd of a branch, behind a NAT,
	// whose upstreams name the queue.
	Proxy bool   `yaml:"proxy"`
	URL   string `yaml:"url"`
	// Format is ps or pdf for a printer of 9100 or LPD, or the language
	// of a printer of labels, receipts or forms (zpl, sbpl, tpcl, escpos,
	// escp) on any of them: a raw queue of CUPS too. Profile names its
	// model (bdf print -profile list); the URL's lang, profile, dpi and
	// width say the same of a raw printer.
	Format       string `yaml:"format"`
	Profile      string `yaml:"profile"`
	PJL          *bool  `yaml:"pjl"`
	Username     string `yaml:"username"`
	PasswordEnv  string `yaml:"password-env"`
	PasswordFile string `yaml:"password-file"`
	// Fingerprint ("sha256:…") pins the certificate of an ipps printer;
	// without it, the first certificate seen is recorded and kept.
	Fingerprint string `yaml:"fingerprint"`
	// Insecure takes any certificate.
	Insecure bool `yaml:"insecure"`
}

PrinterConfig is a printer: its URL (ipp://, ipps://, http://, https://), its user and password when it asks for them, and the fingerprint of its certificate when it is pinned; or a printer of 9100 or LPD (socket://host:9100, lpd://host/queue), the format it takes (ps, the default, or pdf) and whether a PJL header goes before the document (by default, for PDF only).

type QueueConfig

type QueueConfig struct {
	Printers []string `yaml:"printers"`
	Policy   string   `yaml:"policy"`
	// Defaults are the ticket's defaults, with IPP's names (sides,
	// print-color-mode, media …).
	Defaults      map[string]any `yaml:"defaults"`
	Format        string         `yaml:"format"`
	RasterIfLossy bool           `yaml:"raster-if-lossy"`
	MaxInflight   int            `yaml:"max-inflight"`
	// Info and Location describe the queue as an IPP printer
	// (printer-info, the name it is advertised with, and
	// printer-location).
	Info     string `yaml:"info"`
	Location string `yaml:"location"`
}

QueueConfig is a queue of printers.

type RetentionConfig

type RetentionConfig struct {
	Documents Duration `yaml:"documents"`
	Records   Duration `yaml:"records"`
}

RetentionConfig is how long what is done is kept ("168h", "7d").

type Server

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

Server is a print server: a spool and its HTTP API.

func New

func New(ctx context.Context, cfg *Config, o Options) (*Server, error)

New opens the spool of a configuration (spool.db, locked: a second server of the same file is refused) and makes the server. Serve starts it; Close closes a server that was not served.

func (*Server) Close

func (s *Server) Close() error

Close closes the spool of a server that is not served.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler is the server's HTTP handler: the API, /events, /metrics, /healthz and the page of the state.

func (*Server) IPPHandler

func (s *Server) IPPHandler() http.Handler

IPPHandler is the handler of the IPP server (Config.IPP), nil without one: the printers at /ipp/print/<queue>, their icons and pages.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run listens on the configuration's address and serves until ctx ends.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, ln net.Listener) error

Serve starts the spool and serves a listener until ctx ends. Then it stops taking requests, ends the event streams, lets the documents being sent finish for Options.Grace, and closes the spool.

func (*Server) Spool

func (s *Server) Spool() *spool.Spool

Spool is the server's spool.

type Size

type Size int64

Size reads bytes, "512KiB", "256MiB", "10GiB" (or KB, MB, GB).

func (*Size) UnmarshalYAML

func (s *Size) UnmarshalYAML(n *yaml.Node) error

type TLSConfig

type TLSConfig struct {
	Cert string `yaml:"cert"`
	Key  string `yaml:"key"`
}

TLSConfig is the certificate and key of HTTPS.

type TokenConfig

type TokenConfig struct {
	Name   string   `yaml:"name"`
	File   string   `yaml:"file"`
	Env    string   `yaml:"env"`
	Value  string   `yaml:"value"`
	Queues []string `yaml:"queues"`
	Roles  []string `yaml:"roles"`
	// ActAs lets the token name the user of a job (X-BDF-User): an
	// application that submits for its users.
	ActAs bool `yaml:"act-as"`
	// contains filtered or unexported fields
}

TokenConfig is a token: its name (the user of its jobs), its secret (from a file, the environment, or the value itself), the queues it may submit to (all when none), and its roles: submit, manage (others' jobs, accounting), admin (queues, discovery, backup).

type UpstreamConfig

type UpstreamConfig struct {
	URL          string `yaml:"url"`
	Queue        string `yaml:"queue"`
	Username     string `yaml:"username"`
	PasswordEnv  string `yaml:"password-env"`
	PasswordFile string `yaml:"password-file"`
	Fingerprint  string `yaml:"fingerprint"`
	Insecure     bool   `yaml:"insecure"`
	// Poll is how often the jobs are asked for: 10 seconds by default.
	Poll Duration `yaml:"poll"`
	// UUID is the output-device-uuid of this proxy; one made of the
	// spool and the upstream's name by default.
	UUID string `yaml:"uuid"`
}

UpstreamConfig is a server this one fetches jobs from: the URL of its queue (a queue of a printer of proxies there), the queue here the jobs go to, and the token's name and secret there (Basic).

Directories

Path Synopsis
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.
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.

Jump to

Keyboard shortcuts

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