Documentation
¶
Overview ¶
Package docflow is the core of BDF Docflow, a document workflow engine: a topology of nodes a job flows through, as an administrator composes it. Uploaders take documents and data from applications; queues forward to several nodes at once, classes to one of their members in turn, inboxes hold jobs until a person sends them on; displays show jobs as slips on the tablets enrolled there (a warehouse) instead of printing them, and print on paper what nobody opened; printers print; archives keep a copy that is never changed. Jobs enter at the entries: uploaders, CUPS servers (IPP) and the adapters' (docflow/io).
A Manager holds no state of its own: everything is in its Store, so that any request may reach any instance (a container, several, or a function of AWS Lambda). Nothing runs in the background either: what is due is done by Tick, which a scheduler calls (or a timer of the process). The web application is cmd/docflow; Handler is its API, its IPP printers and the devices' endpoints.
Index ¶
- Constants
- Variables
- func CheckCredential(name string) error
- func CheckPreviewURL(raw string) error
- func CleanNames(names []string) []string
- func CleanPath(s string) string
- func CredentialEnv(name string) string
- func Final(err error) error
- func Handler(m *Manager) http.Handler
- func KnownFormats() []string
- func MetaKeyOK(k string) bool
- func MetaText(v any) string
- func NodePath(kind, name string) string
- func PagesView(doc *bdf.Document) (*bdf.View, error)
- func PortHandler(m *Manager, name string) http.Handler
- func Prefixes() []string
- func RegisterIngress(in Ingress)
- func RegisterKind(k Kind)
- func ServesPort(kind string) bool
- func SetSettings(n *Node, v any) error
- func SettingsOf[T any](n *Node) (T, error)
- type App
- type ArchiveRecord
- type ArchivedEntry
- type AuditEntry
- type Board
- type Case
- type Check
- type CheckFailure
- type Choice
- type Converter
- type Delivery
- type DeliveryState
- type Destination
- type Device
- type DownloadEntry
- type Duration
- type Enrollment
- type Failure
- type Fallback
- type Fetch
- type Fetched
- type Field
- type FieldType
- type Fingerprint
- type Flow
- type InboxSummary
- type InboxView
- type Ingress
- type Input
- type Item
- type ItemState
- type Job
- type JobState
- type Kind
- type KindInfo
- type Layout
- type Lease
- type Leg
- type Live
- type LiveNode
- type Made
- type Manager
- func (m *Manager) App(ctx context.Context, id string) (*App, error)
- func (m *Manager) Apps(ctx context.Context) ([]App, error)
- func (m *Manager) Archived(ctx context.Context, name string, v *Viewer, limit int) ([]ArchivedEntry, error)
- func (m *Manager) Audit(ctx context.Context, who, action, subject, detail string)
- func (m *Manager) AuditLog(ctx context.Context, limit int) ([]AuditEntry, error)
- func (m *Manager) Authenticate(ctx context.Context, device, challenge, signature string) (string, time.Time, error)
- func (m *Manager) Board(ctx context.Context, loc string) (*Board, error)
- func (m *Manager) BoardRev(ctx context.Context, loc string) (string, error)
- func (m *Manager) Cancel(ctx context.Context, id string, by Mark) (*Job, error)
- func (m *Manager) CancelSlip(ctx context.Context, id string, by Mark) (*Slip, error)
- func (m *Manager) Challenge() string
- func (m *Manager) Credential(name string) (string, error)
- func (m *Manager) DeleteApp(ctx context.Context, id string) error
- func (m *Manager) DeleteNode(ctx context.Context, name string) error
- func (m *Manager) DeletePerson(ctx context.Context, id string) error
- func (m *Manager) DeleteTemplate(ctx context.Context, node, id string) error
- func (m *Manager) Delivery(ctx context.Context, id string) (*Delivery, error)
- func (m *Manager) Destinations(ctx context.Context, v *Viewer) ([]Destination, error)
- func (m *Manager) Device(ctx context.Context, id string) (*Device, error)
- func (m *Manager) Devices(ctx context.Context, loc string) ([]Device, error)
- func (m *Manager) Discard(ctx context.Context, id string, by Mark) (*Item, error)
- func (m *Manager) Document(ctx context.Context, payload string) (*bdf.Document, error)
- func (m *Manager) Done(ctx context.Context, id string, by Mark) (*Slip, error)
- func (m *Manager) Enroll(ctx context.Context, code, name, key string) (*Device, error)
- func (m *Manager) Entries(ctx context.Context, n *Node, owners []string, limit int) ([]DownloadEntry, error)
- func (m *Manager) Entry(ctx context.Context, node string, job int32) (*DownloadEntry, error)
- func (m *Manager) FreePort(ctx context.Context, except string) (int, error)
- func (m *Manager) GetLayout(ctx context.Context) (*Layout, error)
- func (m *Manager) Inbox(ctx context.Context, name string) (*InboxView, error)
- func (m *Manager) Inboxes(ctx context.Context, v *Viewer) ([]InboxSummary, error)
- func (m *Manager) IssueAppToken(ctx context.Context, id, secret string, scopes []string) (token string, expires time.Time, granted []string, err error)
- func (m *Manager) Item(ctx context.Context, id string) (*Item, error)
- func (m *Manager) Job(ctx context.Context, id string) (*Job, error)
- func (m *Manager) JobOfNumber(ctx context.Context, n int32) (*Job, error)
- func (m *Manager) JobsOf(ctx context.Context, dest string, limit int) ([]Job, error)
- func (m *Manager) KeyedNode(ctx context.Context, kind, name, key string) (*Node, error)
- func (m *Manager) Latest(ctx context.Context, name string, v *Viewer) ([]Job, error)
- func (m *Manager) Live(ctx context.Context, v *Viewer) (*Live, error)
- func (m *Manager) MaySend(ctx context.Context, r *http.Request, dest string) error
- func (m *Manager) MyJobs(ctx context.Context, v *Viewer, limit int) ([]Job, error)
- func (m *Manager) NewEnrollment(ctx context.Context, loc string, ttl time.Duration) (*Enrollment, error)
- func (m *Manager) Node(ctx context.Context, name string) (*Node, error)
- func (m *Manager) Nodes(ctx context.Context) ([]Node, error)
- func (m *Manager) Now() time.Time
- func (m *Manager) Open(ctx context.Context, id string, by Mark) (*Slip, error)
- func (m *Manager) OpenAPI(ctx context.Context, o OpenAPIOptions) ([]byte, error)
- func (m *Manager) Options() Options
- func (m *Manager) Pending(ctx context.Context) ([]Delivery, error)
- func (m *Manager) Person(ctx context.Context, id string) (*Person, error)
- func (m *Manager) Ports() bool
- func (m *Manager) Preview(ctx context.Context, name string, limit int) ([]PreviewJob, error)
- func (m *Manager) PrintSlip(ctx context.Context, id, printer string, by Mark) (*Slip, error)
- func (m *Manager) PutApp(ctx context.Context, in App) (secret string, err error)
- func (m *Manager) PutLayout(ctx context.Context, l Layout) (*Layout, error)
- func (m *Manager) PutNode(ctx context.Context, in Node) (key string, err error)
- func (m *Manager) PutPerson(ctx context.Context, id string, p Person) error
- func (m *Manager) PutTemplate(ctx context.Context, node, id, name string, r io.ReaderAt, size int64) (*Template, error)
- func (m *Manager) RecentJobs(ctx context.Context, limit int) ([]Job, error)
- func (m *Manager) RedeemCode(ctx context.Context, code, verifier, client, redirect string) (token string, expires time.Time, scopes []string, err error)
- func (m *Manager) Release(ctx context.Context, id string, to []string, by Mark) (*Item, error)
- func (m *Manager) RemoveDevice(ctx context.Context, id string) error
- func (m *Manager) RenameNode(ctx context.Context, from, to string) error
- func (m *Manager) Reprint(ctx context.Context, j *Job, dest string, by *Principal) (*Job, error)
- func (m *Manager) ReserveJobNumber(ctx context.Context) (int32, error)
- func (m *Manager) Retry(ctx context.Context, id string) (*Delivery, error)
- func (m *Manager) RotateAppSecret(ctx context.Context, id string) (string, error)
- func (m *Manager) RotateKey(ctx context.Context, name string) (string, error)
- func (m *Manager) Sender(r *http.Request) (by *Principal, ok bool)
- func (m *Manager) Session(ctx context.Context, session string) (*Device, error)
- func (m *Manager) Slip(ctx context.Context, id string) (*Slip, error)
- func (m *Manager) SlipOfJob(ctx context.Context, job int32) (*Slip, error)
- func (m *Manager) StoreKey() any
- func (m *Manager) Submit(ctx context.Context, dest string, in Input) (*Job, error)
- func (m *Manager) Template(ctx context.Context, node, id string) (*Template, error)
- func (m *Manager) Templates(ctx context.Context, node string) ([]Template, error)
- func (m *Manager) Tick(ctx context.Context) (*TickReport, error)
- func (m *Manager) Topology(ctx context.Context) ([]TopoNode, error)
- func (m *Manager) WritePage(ctx context.Context, payload string, pages, page, width int, w io.Writer) error
- func (m *Manager) WritePayload(ctx context.Context, payload string, w io.Writer) error
- func (m *Manager) WritePreviewPage(ctx context.Context, name string, job int32, page int, w io.Writer) (string, error)
- func (m *Manager) WriteTemplate(ctx context.Context, node, id string, w io.Writer) error
- type Mark
- type Match
- type Node
- type OpenAPIOptions
- type Options
- type Out
- func (o *Out) Document(ctx context.Context) (*bdf.Document, error)
- func (o *Out) Expand(s string) string
- func (o *Out) ExpandFunc(s string, esc func(string) string) string
- func (o *Out) ExpandHeader(s string) string
- func (o *Out) ExpandPath(s string) string
- func (o *Out) Manager() *Manager
- func (o *Out) Open(ctx context.Context) (io.ReadCloser, error)
- type Payload
- type Person
- type Point
- type PreviewJob
- type Principal
- type Printed
- type Refusal
- type Release
- type Required
- type Role
- type Rule
- type Signer
- type Slip
- type SlipState
- type Store
- func (s *Store) Close() error
- func (s *Store) PruneStates(ctx context.Context, before time.Time, limit int) (int, error)
- func (s *Store) PutState(ctx context.Context, key string, payload []byte, expires time.Time) error
- func (s *Store) TakeState(ctx context.Context, key string, now time.Time) ([]byte, error)
- type Template
- type Text
- type TickReport
- type TopoNode
- type Trace
- type TraceSide
- type Viewer
- func (v *Viewer) Can(role string) bool
- func (v *Viewer) CanCancel(j *Job) bool
- func (v *Viewer) CanSee(j *Job) bool
- func (v *Viewer) CanSendTo(scope, owner string) bool
- func (v *Viewer) Has(scope string) bool
- func (v *Viewer) Label() string
- func (v *Viewer) Member(group string) bool
- func (v *Viewer) Principal() *Principal
- func (v *Viewer) Submitted(j *Job) bool
- func (v *Viewer) Token() bool
Constants ¶
const ( // ScopePrint sends documents to the entries that list the app. ScopePrint = "print" // ScopePrintTemplate sends data to those entries (for the template // nodes after them). ScopePrintTemplate = "print.template" // ScopeJobsCancel cancels the app's own jobs. ScopeJobsCancel = "jobs.cancel" // ScopeTick calls POST /api/tick (a scheduler). ScopeTick = "tick" // ScopeAdmin uses the API as an administrator (a script). ScopeAdmin = "admin" // ScopeDownload reads the downloaders that list the app // (download.go); of a person's token, the downloaders they may read. ScopeDownload = "download" // ScopeInbox works the inboxes that list the app (inboxapi.go): lists // what they hold, reads its pages and documents, releases and // discards; of a person's token, the inboxes they work. ScopeInbox = "inbox" )
Scopes of an app.
const ( GroupSource = "source" GroupControl = "control" GroupConvert = "convert" GroupSink = "sink" )
The headings of the editor's palette, by role (Kind.Group).
const ( // AccessTopology is the role topology (the admin token, an app with // the scope admin, a person with the role): the default. AccessTopology = "" // AccessViewer is anyone signed in, or with a token. AccessViewer = "viewer" // AccessPublic is anyone: the handler checks for itself. AccessPublic = "public" )
Who a kind's own API (Kind.Handler) answers (Kind.Access).
const ( // PayloadBDF is a .bdf document: what printers, displays and the // pages take. PayloadBDF = "bdf" // PayloadData is data: JSON, YAML, CSV, an Excel workbook or a // Parquet file, which a template node fills a template with. PayloadData = "data" // PayloadAny is any other file as it was received (a PDF, an Office // document, an image …), which a convert node makes a .bdf of. PayloadAny = "any" // PayloadStocked is a file of any format that an inbox or an archive // keeps, sent along its edge to a node that reads it there: HTTP // (pull), where applications fetch it. Where it is kept is where it // comes from and how long it is there: an inbox's while it holds the // job, an archive's for good. Only those send it (Kind.Stocks), and // only along their To, to such a node. PayloadStocked = "stocked" )
Kinds of a payload: what flows along an edge. Every node takes some of them at its input (takes) and sends some on at its output (emits). The graph is typed when a node is put (typed): the kinds that reach every node are inferred from the entries along the edges, and a new edge that brings a kind to a node that does not take it (data to a printer, say) is refused. A change of a node's settings may leave an edge that no longer carries what the node after it takes (an entry taking data now, in front of a printer): the edge stays, broken, for the editor to show and the administrator to mend. A job's payload is checked again at every node it reaches (route), so that a broken edge, or a graph changed while a job was on its way, gives the job a leg of the error there and does not break it.
const ( // KindQueue forwards a job to every node of To: a virtual printer // in front of others, and a fan-out when To has several. KindQueue = "queue" // KindClass sends a job to one of its Members, as a class of CUPS // does: in turn (round-robin), or the first one (failover). A member // that does not take it is skipped for the next. KindClass = "class" // KindInbox keeps a job until a person releases it to one of the // nodes of To (or discards it): a filter worked by hand. KindInbox = "inbox" // KindArchive writes the job's .bdf and a record of it to a store // that is written once and never changed by the manager: an audit // trail (the vault of pm-2 adds the retention of S3 Object Lock). KindArchive = "archive" // KindUpload is an uploader: it takes documents over HTTP (POST // /api/upload/<name>, with the uploader's own key or an app's token), // a document of any format the converter reads, or data for a // template node after it. It forwards the job to every node of To, as // a queue does (upload.go). KindUpload = "upload" // KindDisplay shows the job as a slip on the devices enrolled at the // display (the tablets of a warehouse), and prints on paper what // nobody opened in time (Fallback). KindDisplay = "display" // KindSink keeps the latest documents that reach it, to look at on // the topology (sink.go). KindSink = "sink" // KindFilter sends a job on by rules on what it is (filter.go). KindFilter = "filter" // KindAssert checks the job's metadata and sends on the job that // passes; one right after the node a job is sent to refuses it to the // sender (assert.go). KindAssert = "assert" // KindBranch sends the job along the first of its cases whose checks // it passes, else along its default, as a switch does (branch.go). KindBranch = "branch" // KindTemplate fills one of its templates with the data that reaches // it (kind data) and sends the form on as .bdf (transform.go). KindTemplate = "template" // KindConvert makes a .bdf document of whatever reaches it (a PDF, an // Office document, a CSV file …), as an entry does when it converts, // and sends it on (transform.go). KindConvert = "convert" // KindDownload is a downloader: an exit applications and people // fetch documents from. It lists what an inbox or an archive before it // keeps, each entry under the owner its metadata names, and serves // them at GET /api/download/<name> (download.go). KindDownload = "download" // KindSign signs the .bdf document that reaches it with the key of // the manager, as a witness of who sent it, and sends it on // (signnode.go). KindSign = "sign" )
The core's kinds of node (kinds_core.go): what a job sent to a node becomes. Uploaders are entries; queues, classes, filters and inboxes route; template and convert nodes make a payload; displays, archives, sinks and downloaders are where a job ends. The kinds of the adapters of docflow/io (printers, CUPS servers) are theirs.
const ( AcceptFile = "file" AcceptData = "data" )
What an entry (an uploader, a CUPS server) accepts: documents (PDF, Office, images, .bdf …; the default), or data (JSON, YAML, CSV, Excel, Parquet: what a template node fills).
const ( OutputBDF = "bdf" OutputFile = "file" )
What an entry sends on of a document: the .bdf document made of it (the default), or the file as it was received (kind any).
const ( PolicyRoundRobin = "round-robin" PolicyFailover = "failover" )
Policies of a class.
const ( LegRouted = "routed" LegShown = "shown" LegHeld = "held" LegReleased = "released" LegDiscarded = "discarded" LegPending = "pending" LegDone = "done" LegFailed = "failed" LegCanceled = "canceled" LegKept = "kept" LegListed = "listed" LegDropped = "dropped" LegRefused = "refused" LegError = "error" )
States of a leg.
const ( // PrincipalUser is a person signed in through the IdP (OIDC). PrincipalUser = "user" // PrincipalToken is a sender with a token of the configuration: a // submit token's name, or "admin" for the admin token. PrincipalToken = "token" // PrincipalKey is the key of a keyed entry (an uploader, POST // /api/upload/<name>; an S3 trigger): whoever holds it. PrincipalKey = "key" // PrincipalApp is an app with credentials of its own (apps.go). PrincipalApp = "app" // PrincipalAnonymous is a sender nobody verified (no submit tokens // are configured). PrincipalAnonymous = "anonymous" )
Kinds of principals.
const ( ViaOIDC = "oidc" ViaAdminToken = "admin-token" ViaSubmitToken = "submit-token" ViaNodeKey = "node-key" // ViaClientCredentials is an app's token (POST /oauth/token) or its // Basic client_id:secret. ViaClientCredentials = "client-credentials" // ViaOAuth is a person's token, which a frontend registered as a // public client got for them (the authorization code grant with // PKCE at /oauth/authorize, oauth.go). ViaOAuth = "oauth" ViaNone = "none" )
How a principal was verified.
const ( // RoleTopology changes the topology and what is at it: nodes, // templates, keys, apps, devices, inboxes, deliveries. RoleTopology = "topology" // RoleAudit reads the audit log and every job. RoleAudit = "audit" )
Roles of a person besides being an administrator (who has every role): the web application gives them from the IdP's claims.
const ( // submitter's alone. The scope of one that names none. ScopeShared = "shared" // ScopeGroup: the members of the Owner group send to it, and see its // jobs. ScopeGroup = "group" // ScopePersonal: the Owner person alone (their ID or email). ScopePersonal = "personal" )
Scopes of nodes: who may send to them from the pages, and whose their jobs are.
const ( // SubjectEmail is the person's email, as the IdP verified it (the // default). SubjectEmail = "email" // SubjectSub is the person's subject at the IdP. SubjectSub = "sub" // SubjectID is the person's ID at the manager (Viewer.ID). SubjectID = "id" // SubjectGroup is any of the person's groups. SubjectGroup = "group" )
What of a person a downloader compares with the owner a document's metadata names (Node.Subject).
const ( // TraceSource is the payload a step took, sent on along Original. TraceSource = "source" // TraceOutput is the payload it made, sent on along To. TraceOutput = "output" )
Sides of a trace.
const APIPath = "/api"
APIPath is where the API is. The nodes a request reaches from outside are under it by their kind and their name (NodePath): an uploader takes documents at POST /api/upload/<name>, an inbox is worked at /api/inbox/<name>, a downloader read at /api/download/<name>, and a keyed entry of an adapter takes what it reads at its kind's (/api/s3-trigger/<name>), all on the manager's own server.
const AppTokenFor = 10 * time.Minute
AppTokenFor is how long an app's token lasts; an app takes another with its credentials.
const ChallengeFor = 2 * time.Minute
ChallengeFor is how long a challenge may be signed.
const EnrollCodeLength = 10
EnrollCodeLength is the length of an enrollment code: 50 bits.
const FirstPort = 6310
FirstPort is the first port FreePort gives.
const MaxPageWidth = 2400
MaxPageWidth bounds the width of a page drawn for a device.
const MaxTemplate = 32 << 20
MaxTemplate bounds a template's file.
const OAuthAuthorizePath = "/oauth/authorize"
OAuthAuthorizePath is where a frontend sends the person for a code.
const OAuthTokenPath = "/oauth/token"
OAuthTokenPath is where the apps take their tokens (apps.go).
const OpenAPIPath = "/api/openapi.json"
OpenAPIPath is where the manager serves the OpenAPI document.
const RoleWitness = "witness"
RoleWitness is the role a sign node signs in unless it says another.
const SessionCookie = "bdf_docflow_device"
SessionCookie is the cookie of a device's session.
const ( // UserTokenFor is how long a person's token lasts. UserTokenFor = time.Hour )
Variables ¶
var ( // ErrNotFound is the error of what is not there. ErrNotFound = errors.New("manager: not found") // ErrInvalid is the error of a request that cannot be. ErrInvalid = errors.New("manager: invalid") // ErrConflict is the error of a change that another one beat. ErrConflict = errors.New("manager: changed meanwhile") ErrUnauthorized = errors.New("manager: not authorized") // ErrForbidden is the error of what a known principal may not do. ErrForbidden = errors.New("manager: not allowed") )
var ErrCredential = errors.New("docflow: no such credential")
ErrCredential is the error of a credential named that is not there.
var ErrFormat = errors.New("manager: the document's format is not known")
ErrFormat is the error of a document neither .bdf nor of a format the converter reads, or one the destination does not take.
var ErrLeased = errors.New("manager: the slip is being printed")
ErrLeased is the error of a slip another manager is sending.
var ErrPrint = errors.New("manager: the printer did not print")
ErrPrint is the error of a printer that did not take a slip.
var ErrRefused = errors.New("manager: refused")
ErrRefused is the error of a job an assert refused to its sender (Refusal).
var ErrStore = errors.New("manager: store")
ErrStore is the error of a store that cannot keep a manager's records.
var ErrUnsupported = errors.New("docflow: not supported")
ErrUnsupported is the error of what a node cannot do yet (a printer a branch fetches from).
Functions ¶
func CheckCredential ¶
CheckCredential checks the shape of a credential's name: "" is none.
func CheckPreviewURL ¶
CheckPreviewURL takes the URL of a printer on a fake printer farm's API (tools/fakeprinter), whose pages are shown beside a node.
func CleanNames ¶
CleanNames trims a list of node names, without empty ones and duplicates: the edges of a node's settings.
func CleanPath ¶
CleanPath makes a path relative and clean: no leading slash, no empty, . or .. segment.
func CredentialEnv ¶
CredentialEnv is the environment variable of a credential's value.
func Handler ¶
Handler serves a manager over HTTP:
the ingresses' prefixes (Prefixes: docflow/io/ipp's /ipp/print)
/api/… the API (bearer AdminToken, or a session of the pages)
/api/upload/{name}, /api/inbox/{name}, the nodes reached from outside, under their kind (keys,
/api/download/{name} apps' tokens, people)
/oauth/… the apps' and the frontends' tokens
/device/… the devices' endpoints (their session)
It is mounted on the web application's mux; it holds nothing between requests.
func KnownFormats ¶
func KnownFormats() []string
KnownFormats names the formats an entry may take: the converter's (those registered: converter/all has every one) and the manager's own.
func MetaText ¶
MetaText is a metadata value as text: a string as it is, a number as it is written, anything else as JSON.
func PagesView ¶
PagesView is the view of a document whose pages are printed, drawn and counted: its first fixed or flow view of pages, else a scroll view.
func PortHandler ¶
PortHandler serves a node on its own port: what it does is read from the node at each request, so that its settings changing need no restart; a node that is gone, or has no port any more, answers 404.
func Prefixes ¶
func Prefixes() []string
Prefixes are the paths of the ingresses registered, for the web application to mount Handler at.
func RegisterIngress ¶
func RegisterIngress(in Ingress)
RegisterIngress makes an ingress known, once, in an init.
func RegisterKind ¶
func RegisterKind(k Kind)
RegisterKind makes a kind of node known. It is called once for a kind, in an init; a name registered twice panics.
func ServesPort ¶
ServesPort tells a kind whose node listens on a port of its own (Node.Port, PortHandler): an entry of an adapter that serves one (Kind.Serve: a CUPS server).
func SetSettings ¶
SetSettings writes a value of the kind's own type as a node's settings (a Check that cleans them, say): what encoding/json makes of it.
func SettingsOf ¶
SettingsOf reads a node's settings (Node.Settings) into a value of the kind's own type, its fields' defaults first (a setting not there is its default), as encoding/json reads them: the fields' keys are the JSON keys. A node of a kind that is not registered reads its settings alone.
Types ¶
type App ¶
type App struct {
// ID is the client_id: a name.
ID string `json:"id"`
Title string `json:"title,omitempty"`
// Scopes are what it may do (appScopes); print when none is given.
Scopes []string `json:"scopes"`
// Group is the group whose members see the app's jobs, when the
// destination gives them none.
Group string `json:"group,omitempty"`
// Public tells a public client: a frontend in people's browsers,
// which keeps no secret and gets tokens of the people using it with
// the authorization code grant (oauth.go), sent back to one of its
// RedirectURIs.
Public bool `json:"public,omitempty"`
RedirectURIs []string `json:"redirect_uris,omitempty"`
// SecretHash is the argon2id hash of its secret, never the secret;
// the API leaves it out. A public client has none.
SecretHash string `json:"secret_hash,omitempty"`
// Disabled refuses its credentials, keeping it.
Disabled bool `json:"disabled,omitempty"`
Created time.Time `json:"created"`
LastUsed time.Time `json:"last_used,omitzero"`
}
App is an application registered to send.
type ArchiveRecord ¶
type ArchiveRecord struct {
Job int32 `json:"job"`
Dest string `json:"dest"`
Name string `json:"name,omitempty"`
SubmittedBy *Principal `json:"submitted_by,omitempty"`
ClaimedUser string `json:"claimed_user,omitempty"`
Source string `json:"source"`
Kind string `json:"kind"`
Format string `json:"format,omitempty"`
Pages int `json:"pages,omitempty"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
Received time.Time `json:"received"`
Archived time.Time `json:"archived"`
Archive string `json:"archive"`
Payload string `json:"payload"`
Object string `json:"object"`
Meta map[string]any `json:"meta,omitempty"`
Payloads []Payload `json:"payloads"`
Legs []Leg `json:"legs"`
Trace *Trace `json:"trace,omitempty"`
}
ArchiveRecord is the record an archive keeps beside the payload it wrote: the job, the payload (Kind, Format, Pages, Size and SHA256 are its), its metadata, the job's way so far (Legs, Payloads), and the trace of the step the payload came out of or went into, which names the other side's objects (trace.go).
type ArchivedEntry ¶
type ArchivedEntry struct {
Job int32 `json:"job"`
Name string `json:"name,omitempty"`
Kind string `json:"kind"`
Format string `json:"format,omitempty"`
Pages int `json:"pages,omitempty"`
Size int64 `json:"size"`
Received time.Time `json:"received"`
Archived time.Time `json:"archived"`
Key string `json:"key"`
Object string `json:"object"`
// SubmittedBy, ClaimedUser and Group are the job's: who sees it.
SubmittedBy *Principal `json:"submitted_by,omitempty"`
ClaimedUser string `json:"claimed_user,omitempty"`
Group string `json:"group,omitempty"`
}
ArchivedEntry is a payload an archive wrote: the job as it was then, and the key of its objects in the archive's store (Object the payload, Key + ".json" the record).
type AuditEntry ¶
type AuditEntry struct {
ID string `json:"id"`
At time.Time `json:"at"`
Who string `json:"who"`
Action string `json:"action"`
Subject string `json:"subject,omitempty"`
Detail string `json:"detail,omitempty"`
}
AuditEntry is an action a person, a device or a sender took.
type Board ¶
type Board struct {
Location string `json:"location"`
Title string `json:"title"`
Rev string `json:"rev"`
Open []Slip `json:"open"`
Ended []Slip `json:"ended"`
}
Board is what a location's devices show: the open slips, oldest first, and the ended ones, latest first, those not expired. Rev changes whenever any of them does.
type Case ¶
type Case struct {
Name string `json:"name,omitempty"`
When []Check `json:"when"`
To []string `json:"to,omitempty"`
}
Case is an arm of a branch: where a job that passes every check of When goes. Name labels the arm ("case <n>" when it has none).
type Check ¶
type Check struct {
Key string `json:"key"`
Optional bool `json:"optional,omitempty"`
Pattern string `json:"pattern,omitempty"`
Min *float64 `json:"min,omitempty"`
Max *float64 `json:"max,omitempty"`
Enum []string `json:"enum,omitempty"`
Message string `json:"message,omitempty"`
}
Check is a condition on a key of a job's metadata, as the nodes see it (metaView: the sender's keys, the entry's, the manager's $ keys, name and user, and the payload's $kind, $format, $pages …). The key must have a value that is not empty, unless Optional, which passes a job without it; a value must then match Pattern (RE2, anywhere in it: ^…$ for the whole), be a number from Min to Max, and be one of Enum, those given. Message is what a failure says instead of the check's own words.
type CheckFailure ¶
type CheckFailure struct {
Node string `json:"node"`
Key string `json:"key"`
Error string `json:"error"`
}
CheckFailure is a check a job failed at a node.
type Choice ¶
type Choice struct {
Value string `json:"value"`
// Label is how it is said; none, the value.
Label Text `json:"label,omitempty"`
}
Choice is one of the values a field of FieldEnum takes.
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.
Convert(ctx context.Context, r io.ReaderAt, size int64, format, name, password string) (*bdf.Document, []string, error)
}
Converter makes .bdf documents of files of other formats, as print/printconv does (the spool's converter has the same methods).
type Delivery ¶
type Delivery struct {
ID string `json:"id"`
Job int32 `json:"job"`
Name string `json:"name,omitempty"`
// Node is the printer, the archive, the class or the transforming
// node the job was routed to; Printer the printer it goes to now (a
// member, of a class). Payload is the job's payload it takes.
Node string `json:"node"`
Kind string `json:"kind"`
Payload string `json:"payload,omitempty"`
Printer string `json:"printer,omitempty"`
Class string `json:"class,omitempty"`
// Tried are the members of the class that did not take it, so that
// the next try goes to another.
Tried []string `json:"tried,omitempty"`
State DeliveryState `json:"state"`
Created time.Time `json:"created"`
Attempts int `json:"attempts,omitempty"`
LastError string `json:"last_error,omitempty"`
RetryAt time.Time `json:"retry_at,omitzero"`
Lease *Lease `json:"lease,omitempty"`
// Result is the printer's job id, or the archive's key.
Result string `json:"result,omitempty"`
Done time.Time `json:"done,omitzero"`
// Trace is the step the payload came out of, or went into, on its
// way here (trace.go): an archive writes it into its record.
Trace *Trace `json:"trace,omitempty"`
// Cause is the failure that sent the job here along an on_error edge.
Cause *Failure `json:"cause,omitempty"`
}
Delivery is a job on its way to a printer or an archive, or a step of a template or a convert node: made when the job is routed, done by a tick (or right away, in the background of a process) under a lease, tried again after a failure.
type DeliveryState ¶
type DeliveryState string
DeliveryState is where a delivery is.
const ( DeliveryPending DeliveryState = "pending" DeliveryDone DeliveryState = "done" DeliveryFailed DeliveryState = "failed" DeliveryCanceled DeliveryState = "canceled" )
type Destination ¶
type Destination struct {
Name string `json:"name"`
Kind string `json:"kind"`
Title string `json:"title,omitempty"`
Scope string `json:"scope,omitempty"`
Owner string `json:"owner,omitempty"`
// Source tells an entry, where documents come into the topology: the
// one kind of node a person without the role topology sends to.
Source bool `json:"source,omitempty"`
}
Destination is a node as a person choosing where to print sees it.
type Device ¶
type Device struct {
ID string `json:"id"`
Location string `json:"location"`
Name string `json:"name"`
Key string `json:"key"` // ECDSA P-256 public key, SPKI DER in base64
Enrolled time.Time `json:"enrolled"`
LastSeen time.Time `json:"last_seen,omitzero"`
}
Device is a tablet enrolled at a display (Location is its name). It proves itself with a key it made and cannot export (WebCrypto, non-extractable): the manager keeps the public key.
type DownloadEntry ¶
type DownloadEntry struct {
Job int32 `json:"job"`
Name string `json:"name,omitempty"`
Kind string `json:"kind"`
Format string `json:"format,omitempty"`
Pages int `json:"pages,omitempty"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
// Received is when the job was received, Listed when it reached the
// downloader.
Received time.Time `json:"received"`
Listed time.Time `json:"listed"`
// Archive is the archive that wrote it, Key the key of its objects
// there and Object the payload's object (the record is Key +
// ".json"); or Inbox is the inbox that holds it, and Item the item.
// Payload is the payload's id in the job.
Archive string `json:"archive,omitempty"`
Key string `json:"key,omitempty"`
Object string `json:"object,omitempty"`
Inbox string `json:"inbox,omitempty"`
Item string `json:"item,omitempty"`
Payload string `json:"payload,omitempty"`
// Trace is the step the document came out of or went into, which
// names the other side's objects (trace.go).
Trace *Trace `json:"trace,omitempty"`
// Owner is whose the document is: the value of the downloader's By in
// the job's metadata; empty when the job had none.
Owner string `json:"owner,omitempty"`
// Fields are the metadata the downloader copies (Node.Fields), as text.
Fields map[string]string `json:"fields,omitempty"`
// SubmittedBy, ClaimedUser and Group are the job's: who sent it, and
// whose it is when the downloader has no By.
SubmittedBy *Principal `json:"submitted_by,omitempty"`
ClaimedUser string `json:"claimed_user,omitempty"`
Group string `json:"group,omitempty"`
}
DownloadEntry is a document a downloader lists: the job as it reached the downloader, where it is kept (an archive, or an inbox), and whose it is.
type Duration ¶
Duration is a time.Duration written as text: "90s", "10m", "2h", and "14d" for days.
func ParseDuration ¶
ParseDuration reads a Duration: time.ParseDuration's form, or a whole number of days ("14d").
func (Duration) MarshalJSON ¶
func (*Duration) UnmarshalJSON ¶
type Enrollment ¶
type Enrollment struct {
Code string `json:"code"`
Location string `json:"location"`
Expires time.Time `json:"expires"`
}
Enrollment is a code that adds one device to a location.
type Failure ¶
Failure is a send or a step that failed for good, which the job left along an on_error edge.
type Fallback ¶
Fallback is the printer that prints a display's slips on paper, and after how long an unopened slip is printed (0: only while no device is connected).
type Fetch ¶
type Fetch struct {
Node *Node
// Body is the request's body, of 1 MiB at most.
Body []byte
// contains filtered or unexported fields
}
Fetch is a request to a keyed entry that carries a reference (Kind.Fetch).
type Fetched ¶
type Fetched struct {
Name string
Meta map[string]any
Body io.ReadCloser
}
Fetched is the document a reference names: its name, the metadata it comes with (as a sender's), and its bytes, read once and closed.
type Field ¶
type Field struct {
// Key is the setting's key: letters, digits and _, starting with a
// letter.
Key string `json:"key"`
Type FieldType `json:"type"`
// Title is the field as it is said; Help what it is for, under the
// field; Placeholder what an empty field shows.
Title Text `json:"title,omitempty"`
Help Text `json:"help,omitempty"`
Placeholder Text `json:"placeholder,omitempty"`
// Required refuses a node without the setting (empty is without),
// when the settings of If have the values given (as Required.If);
// always, with no If.
Required bool `json:"required,omitempty"`
If map[string]string `json:"if,omitempty"`
// Choices are the values a FieldEnum takes.
Choices []Choice `json:"choices,omitempty"`
// Default is the value SettingsOf reads for a setting that is not
// there (a JSON value of the field's type); the editor shows it.
Default any `json:"default,omitempty"`
// Expands tells a field whose value has {{meta.<key>}} replaced by
// the job's metadata (the editor says so).
Expands bool `json:"expands,omitempty"`
}
Field is a setting of a kind of node of its own: its key in Node.Settings, what it takes, and how the editor shows it.
type FieldType ¶
type FieldType string
FieldType is what a field of a kind's own settings takes.
const ( // FieldString is a line of text. FieldString FieldType = "string" // FieldText is text of several lines. FieldText FieldType = "text" // FieldInt is a whole number. FieldInt FieldType = "int" // FieldBool is yes or no. FieldBool FieldType = "bool" // FieldDuration is a Duration, written as "30s", "10m", "2h" or "14d". FieldDuration FieldType = "duration" // FieldEnum is one of the field's Choices. FieldEnum FieldType = "enum" // FieldCredential is the name of a credential (credential.go), never // a secret. FieldCredential FieldType = "credential" // FieldPath is a path or a key with {{meta.<key>}} in it, which the // kind expands (Out.ExpandPath). FieldPath FieldType = "path" // FieldJSON is any JSON value, as it is. FieldJSON FieldType = "json" )
type Fingerprint ¶
type Fingerprint struct {
ID string `json:"id"`
Node string `json:"node"`
Role string `json:"role"`
}
Fingerprint is a step a payload's lineage went through: the step's id (a Trace's), its node, and the side the lineage was on (TraceSource: what the step took, TraceOutput: what it made).
type Flow ¶
type Flow struct {
Job int32 `json:"job"`
Name string `json:"name,omitempty"`
From string `json:"from"`
To string `json:"to"`
State string `json:"state"`
At time.Time `json:"at"`
}
Flow is a job that went from one node to the next.
type InboxSummary ¶
type InboxSummary struct {
Name string `json:"name"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
To []string `json:"to"`
Held int `json:"held"`
Rev string `json:"rev"`
}
InboxSummary is an inbox as GET /api/inbox lists it: the nodes it releases to, and how many items it holds.
type InboxView ¶
type InboxView struct {
Name string `json:"name"`
Title string `json:"title"`
To []string `json:"to"`
Rev string `json:"rev"`
Held []Item `json:"held"`
Ended []Item `json:"ended"`
}
InboxView is an inbox as a person works it: the items held, oldest first, and the ended ones still shown, latest first.
type Ingress ¶
type Ingress struct {
Name string
// Prefix is the path its requests are under, which the web
// application mounts Handler at.
Prefix string
// Mount adds its routes to the engine's handler.
Mount func(m *Manager, mux *http.ServeMux)
// Address is where a node is reached by it; "" none.
Address func(n *Node) string
}
Ingress is a way into the topology besides the entries: a protocol on which every node (or every one that does not turn it off) is a destination, as every node is an IPP printer at /ipp/print/<name>.
type Input ¶
type Input struct {
// Name is the job's name (job-name, or the file's).
Name string
// By is who sent it, as verified; nil is an anonymous sender.
By *Principal
// ClaimedUser is who the sender says sent it (requesting-user-name).
ClaimedUser string
// Source is "ipp", "api", the kind of the keyed entry it came in at
// ("upload", "s3-trigger") or "reprint".
Source string
// Doc is what was sent, of Size bytes: .bdf, data, or what the
// converter reads.
Doc io.ReaderAt
Size int64
// ContentType is the request's, when the sender gave one: it tells
// data apart (application/json, text/csv …) where the content and
// the name do not.
ContentType string
// Meta is the metadata the sender gave (meta.go).
Meta map[string]any
// Number is the job's number when one was taken before the document
// came (ReserveJobNumber: IPP's Create-Job tells the job's id before
// Send-Document brings the document); 0 takes the next.
Number int32
}
Input is a document, or data, sent to a destination.
type Item ¶
type Item struct {
ID string `json:"id"`
Job int32 `json:"job"`
Inbox string `json:"inbox"`
Name string `json:"name,omitempty"`
SubmittedBy *Principal `json:"submitted_by,omitempty"`
ClaimedUser string `json:"claimed_user,omitempty"`
Dest string `json:"dest"`
// Payload is the job's payload held here, and Trace the step it came
// out of (trace.go), which goes on with it when it is released.
Payload string `json:"payload,omitempty"`
Trace *Trace `json:"trace,omitempty"`
Pages int `json:"pages"`
Received time.Time `json:"received"`
State ItemState `json:"state"`
// Released tells where it went and who sent it; Discarded who
// discarded it (or canceled the job).
Released *Release `json:"released,omitempty"`
Discarded *Mark `json:"discarded,omitempty"`
// Listed are the downloaders that list it while it is held.
Listed []string `json:"listed,omitempty"`
}
Item is a job held in an inbox until a person releases it.
type Job ¶
type Job struct {
ID string `json:"id"`
Number int32 `json:"number"`
// Dest is the node the sender sent it to.
Dest string `json:"dest"`
Name string `json:"name,omitempty"`
// SubmittedBy is who sent it, as the manager verified it; ownership
// and scope come from it alone.
SubmittedBy *Principal `json:"submitted_by,omitempty"`
// ClaimedUser is who the sender said sent it (requesting-user-name,
// ?user= of the API, the user of an uploader's data): shown, never
// trusted.
ClaimedUser string `json:"claimed_user,omitempty"`
// Group is the group whose members see the job besides its
// submitter: the destination's (or, of a location, its fallback
// printer's) when it was received. Empty: the submitter's alone.
Group string `json:"group,omitempty"`
Source string `json:"source"`
Kind string `json:"kind,omitempty"`
Format string `json:"format,omitempty"`
Pages int `json:"pages"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
Received time.Time `json:"received"`
// Meta is the job's metadata: what the sender gave (a claim, shown
// and routed by, never trusted), what the entry added, and what the
// manager verified (the keys that start with $). See meta.go.
Meta map[string]any `json:"meta,omitempty"`
Payloads []Payload `json:"payloads"`
State JobState `json:"state"`
Ended time.Time `json:"ended,omitzero"`
Canceled *Mark `json:"canceled,omitempty"`
Legs []Leg `json:"legs"`
// Live counts the records that still need the document (slips,
// items, pending deliveries): the job and the document are removed
// when it ended and nothing needs it.
Live int `json:"live"`
}
Job is what a sender sent to a destination (a document, or data), and its way through the topology: a leg for each node it reached, and the payloads the nodes made on the way. Kind, Format, Pages, Size and SHA256 are the received payload's (Format the format received, before an entry converted it). The payloads are kept for every slip, item and delivery of the job.
type JobState ¶
type JobState string
JobState is where a job is, over all the nodes it reached.
const ( // JobProcessing: a delivery to a printer or an archive is pending. JobProcessing JobState = "processing" // JobHeld: an inbox holds it, and nothing else is pending. JobHeld JobState = "held" // JobCompleted: every node took it. JobCompleted JobState = "completed" // JobCanceled: the sender or an administrator canceled it. JobCanceled JobState = "canceled" // JobAborted: a delivery failed for good, or an assert refused it. JobAborted JobState = "aborted" )
type Kind ¶
type Kind struct {
Name string
// Title is the kind as it is said ("CUPS server"); Name by default.
Title string
Role Role
// Takes are the kinds of payload its input takes (PayloadBDF,
// PayloadData, PayloadAny, PayloadStocked); none, every one but
// PayloadStocked.
Takes []string
// PassesOn tells a kind that sends on what reaches it (a router, an
// entry, an archive): its input takes what the nodes after it take,
// and it is typed by its first edge.
PassesOn bool
// Stocks tells a kind that keeps what reaches it (an inbox while it
// holds the job, an archive for good): along its To, to a node that
// takes a stocked file (a downloader), it sends that, read from where
// it keeps it, and what reaches it along the others.
Stocks bool
// Makes is the kind of payload it sends on whatever reaches it (a
// template node's .bdf); none, what reaches it.
Makes string
// Fixed keeps a node of the kind from becoming another kind, and
// another from becoming one of it: its records name it (a display's
// slips, a printer's deliveries).
Fixed bool
// Check checks the settings of a node of the kind and copies them
// from in to n, which PutNode made of the settings every kind has
// (and, of an entry, those of every entry). An error of ErrInvalid is
// the caller's.
Check func(ctx context.Context, m *Manager, in Node, n *Node) error
// Required are the settings Check refuses a node without, for the
// editor to mark before the node is put: those of a kind set as JSON
// (an adapter's) at least.
Required []Required
// Ready tells whether the engine can send to a node of an exit now
// (a printer a branch fetches from: not yet). Its error stops a send
// for good.
Ready func(n *Node) error
// Send sends a payload out of the topology (an exit): a job that
// reaches the node becomes a delivery, done in the background at
// least once and tried again after a failure (Final: never again).
// It returns what to record of the send (the printer's job id).
Send func(ctx context.Context, o *Out) (result string, err error)
// Serve serves a node of an entry on its own port (Node.Port): a
// protocol of its own, as a CUPS server's IPP is; what applications
// call is at the API (/api/<kind>/<name>), on the manager's server.
Serve func(m *Manager, n *Node) http.Handler
// Step is the step of a node of the kind (a render or a notify
// node): a job that reaches the node becomes a delivery, done in the
// background at least once as Send is, and the job goes on from the
// node's To with what Step made, or, with nil, with what reached it.
Step func(ctx context.Context, o *Out) (*Made, error)
// Keyed gives a node of an entry a key, as an uploader has: POST
// /api/<kind>/<name> with it sends to the node (an S3 Trigger's
// /api/s3-trigger/<name>).
Keyed bool
// Fetch takes what a request to a keyed entry carries, a reference
// (an S3 event), and reads the document it names; none, the body is
// the document.
Fetch func(ctx context.Context, o *Fetch) (*Fetched, error)
// FetchSchema is the JSON Schema of the reference Fetch reads, for the
// OpenAPI document (openapi.go); none, any JSON object.
FetchSchema map[string]any
// Discover asks the far side of a node's settings what is there, for
// the editor to pick from before the node is saved (the queues of a
// CUPS server): POST /api/kinds/<kind>/discover with the settings. A
// far side that does not answer is ErrPrint.
Discover func(ctx context.Context, m *Manager, in Node) (any, error)
// What the editor and the manual show of the kind, and the settings
// of a kind of its own (fields.go). Titles is the kind as it is said,
// by language (Title is its English, for a kind that sets that
// alone); Help what it does, in a line, under its name in the
// palette. Group is the heading of the palette it is under: source,
// control, convert or sink by its role, or one of the kind's own.
// Icon is drawn on the node: the paths of a 24 by 24 drawing, stroked
// (as the editor's own are); none, the role's. Doc is the kind's
// chapter of the manual (Markdown), shown at /help/nodes. Picks tells
// a router that sends on by rules or checks (a filter, an assert, a
// branch), which the editor colors apart from one that forwards.
Titles Text
Help Text
Group string
Icon []string
Doc Text
Picks bool
// Fields are the settings of a kind of its own (Node.Settings): the
// editor makes a form of them, and PutNode checks a node's settings
// against them before Check sees them. A kind of the core and the
// adapters has none: its settings are the fields of Node.
Fields []Field
// Handler serves the kind's own API, at /api/<kind>/<name>/… of every
// node of the kind (the name is the request's PathValue "name"), to
// whoever Access lets: the role topology by default.
Handler func(m *Manager) http.Handler
Access string
// contains filtered or unexported fields
}
Kind is a kind of node.
type KindInfo ¶
type KindInfo struct {
Name string `json:"name"`
Title string `json:"title"`
Role Role `json:"role"`
Takes []string `json:"takes"`
PassesOn bool `json:"passes_on,omitempty"`
Stocks bool `json:"stocks,omitempty"`
Makes string `json:"makes,omitempty"`
Fixed bool `json:"fixed,omitempty"`
// SendsOut tells an exit whose jobs are sent out of the topology
// (Kind.Send: a printer); Port an entry that listens on a port of
// its own (a CUPS server).
SendsOut bool `json:"sends_out,omitempty"`
Port bool `json:"port,omitempty"`
// Step tells a kind whose step is done in the background (render,
// notify); Keyed an entry with a key of its own, at
// /api/<kind>/<name>.
Step bool `json:"step,omitempty"`
Keyed bool `json:"keyed,omitempty"`
// Discovers tells a kind whose far side is asked what is there
// (Kind.Discover).
Discovers bool `json:"discovers,omitempty"`
// Required are Kind.Required, and the fields of the kind's own that
// are required.
Required []Required `json:"required,omitempty"`
// Titles and Help are the kind's name and what it does, by language;
// Group the heading of the palette it is under; Icon its drawing;
// Picks a router that picks by rules; Prints an exit a display's
// fallback prints on; Fields the settings of a kind of its own.
Titles Text `json:"titles"`
Help Text `json:"help,omitempty"`
Group string `json:"group"`
Icon []string `json:"icon,omitempty"`
Picks bool `json:"picks,omitempty"`
Prints bool `json:"prints,omitempty"`
Fields []Field `json:"fields,omitempty"`
}
KindInfo is a kind as GET /api/kinds tells it.
type Lease ¶
type Lease struct {
Owner string `json:"owner"`
Until time.Time `json:"until"`
Printer string `json:"printer"`
Why string `json:"why"`
Device string `json:"device,omitempty"`
}
Lease is a manager sending a slip.
type Leg ¶
type Leg struct {
Node string `json:"node"`
Kind string `json:"kind"`
// From is the node that forwarded it ("" at the destination).
From string `json:"from,omitempty"`
At time.Time `json:"at"`
// State is routed (queue, class), shown or canceled (display), held,
// released or discarded (inbox), pending, done, failed or canceled
// (printer, archive), kept (sink), listed (downloader), refused (assert),
// or error when the node could not take it.
State string `json:"state"`
// Ref is the slip, the item or the delivery made here.
Ref string `json:"ref,omitempty"`
// Member is the member a class chose, the rule of a filter, the case
// of a branch, or the owner a downloader listed the job for.
Member string `json:"member,omitempty"`
// Payload is the payload the node got, and Made the one it made of it
// (a template or a convert node).
Payload string `json:"payload,omitempty"`
Made string `json:"made,omitempty"`
Error string `json:"error,omitempty"`
}
Leg is a node a job reached, and what became of it there.
type Live ¶
type Live struct {
// Rev changes when anything below does: a client polls with it
// (If-None-Match), and gets 304 while it is the same.
Rev string `json:"rev"`
At time.Time `json:"at"`
Nodes map[string]LiveNode `json:"nodes"`
// Flows are the legs of the last flowWindow, oldest first.
Flows []Flow `json:"flows"`
}
Live is the topology's activity as a viewer sees it.
type LiveNode ¶
type LiveNode struct {
// Held counts the items an inbox holds, Open the slips open on a
// display, Pending the deliveries waiting at a printer, an archive or
// a class, and Failed those given up.
Held int `json:"held,omitempty"`
Open int `json:"open,omitempty"`
Pending int `json:"pending,omitempty"`
Failed int `json:"failed,omitempty"`
// Refused counts the jobs an assert refused.
Refused int `json:"refused,omitempty"`
// Recent counts the jobs that reached the node in the last
// recentWindow.
Recent int `json:"recent,omitempty"`
// Kept counts the jobs a sink keeps, and Latest is the newest of
// them (its id); Listed counts the jobs a downloader lists.
Kept int `json:"kept,omitempty"`
Latest string `json:"latest,omitempty"`
Listed int `json:"listed,omitempty"`
// Thumb is where the first page of what the node shows is drawn (a
// path of the API, which takes ?w=): the newest document a sink
// keeps, the newest slip open on a display, the newest item an inbox
// holds, the newest .bdf document an archive wrote.
Thumb string `json:"thumb,omitempty"`
}
LiveNode is what is at a node now, of the jobs the viewer sees.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is a view of a Store. It is cheap to make: an instance may make one per request.
func (*Manager) Archived ¶
func (m *Manager) Archived(ctx context.Context, name string, v *Viewer, limit int) ([]ArchivedEntry, error)
Archived returns the latest entries an archive wrote that the viewer may see, newest first, at most limit (defaultShown when 0).
func (*Manager) Authenticate ¶
func (m *Manager) Authenticate(ctx context.Context, device, challenge, signature string) (string, time.Time, error)
Authenticate checks a device's signature of a challenge (ECDSA P-256 with SHA-256, as WebCrypto makes it: r and s of 32 bytes each, or ASN.1) and returns a session for it, and when it ends.
func (*Manager) BoardRev ¶
BoardRev returns the revision of a location's board, which a device compares with the one it has before reading the board again.
func (*Manager) Cancel ¶
Cancel cancels a job: its slips not done leave the boards, its items leave their inboxes, and its deliveries not sent are not. A job that ended is canceled while a slip of it is still open (a slip is done by its reader, after the job completed).
func (*Manager) CancelSlip ¶
CancelSlip cancels a slip that is not done: it leaves the devices, with a mark that it was canceled. The job goes on elsewhere; Cancel cancels the job.
func (*Manager) Challenge ¶
Challenge returns a challenge for a device to sign: it expires after ChallengeFor.
func (*Manager) Credential ¶
Credential reads the value of a credential: its environment variable, else its file in Options.CredentialDir (without a trailing line break). The error names the credential, never a value.
func (*Manager) DeleteApp ¶
DeleteApp removes an app; one a node lists (an entry, a downloader, an inbox) stays.
func (*Manager) DeleteNode ¶
DeleteNode removes a node, with a template node's templates. One another node sends to stays; an inbox with items held stays. A display's slips and devices stay until it is added again; an archive's store keeps what it wrote, not the list of the latest.
func (*Manager) DeletePerson ¶
DeletePerson forgets a person; they are kept again at their next login.
func (*Manager) DeleteTemplate ¶
DeleteTemplate removes a template of a node.
func (*Manager) Destinations ¶
Destinations returns the nodes a viewer may send to: a person, the sources of their scopes (all the nodes of them, with the role topology); an app, the entries that list it.
func (*Manager) Enroll ¶
Enroll adds a device with a code: the code is used up, and the device is of the code's location. key is the device's public key, SPKI DER in base64 (WebCrypto's exportKey("spki")).
func (*Manager) Entries ¶
func (m *Manager) Entries(ctx context.Context, n *Node, owners []string, limit int) ([]DownloadEntry, error)
Entries lists the entries of the lists named, newest first, up to limit: every one's (""), or the owners' (an owner for each of a person's groups).
func (*Manager) FreePort ¶
FreePort returns the first port from FirstPort that no node but the one named has, for an entry of an adapter that listens on a port of its own (a CUPS server) put without one.
func (*Manager) IssueAppToken ¶
func (m *Manager) IssueAppToken(ctx context.Context, id, secret string, scopes []string) (token string, expires time.Time, granted []string, err error)
IssueAppToken checks an app's credentials and makes a token of the scopes asked (none: every one of the app's), and tells when it ends.
func (*Manager) JobOfNumber ¶
JobOfNumber returns the job of a number.
func (*Manager) Latest ¶
Latest returns the jobs a sink keeps, newest first: those the viewer may see (nil: every one).
func (*Manager) MaySend ¶
MaySend refuses an app a destination whose entry does not let it send to; anyone else may.
func (*Manager) MyJobs ¶
MyJobs returns the last jobs a viewer may see, latest first: their own, their groups', every job for an administrator.
func (*Manager) NewEnrollment ¶
func (m *Manager) NewEnrollment(ctx context.Context, loc string, ttl time.Duration) (*Enrollment, error)
NewEnrollment makes a one-time code for a display, valid for ttl (default 15 minutes).
func (*Manager) OpenAPI ¶
OpenAPI returns the OpenAPI 3.1 document of the endpoints the topology publishes (JSON).
func (*Manager) Ports ¶
Ports tells whether nodes may have ports of their own here (not on a serverless deployment: Options.NoPorts).
func (*Manager) Preview ¶
Preview lists the latest jobs a printer's fake printer received, the newest first (at most limit), with the pages read back of the newest.
func (*Manager) PutApp ¶
PutApp registers an app or changes it: its scopes, title, group and whether it is disabled. A new app gets a secret, returned once; an app keeps its (RotateAppSecret makes a new one). A public client gets none: its redirect URIs are checked instead.
func (*Manager) PutLayout ¶
PutLayout moves nodes: the positions given replace those of the same names; a position of a node that is gone is dropped.
func (*Manager) PutNode ¶
PutNode adds a node or replaces its settings; the settings of other kinds are dropped. An uploader added gets a key, returned once (Key); PutNode keeps the key and the templates of an uploader that is one already (RotateKey makes a new key).
func (*Manager) PutTemplate ¶
func (m *Manager) PutTemplate(ctx context.Context, node, id, name string, r io.ReaderAt, size int64) (*Template, error)
PutTemplate keeps a template of a template node under an id, replacing one there. name is its file name, which tells the format of a plain file (a compiled template tells its own).
func (*Manager) RecentJobs ¶
RecentJobs returns the last jobs of every destination, latest first.
func (*Manager) RedeemCode ¶
func (m *Manager) RedeemCode(ctx context.Context, code, verifier, client, redirect string) (token string, expires time.Time, scopes []string, err error)
RedeemCode exchanges a code for a person's token: the code is taken once, and is the client's, for the redirect URI it was sent to, with the verifier of its challenge.
func (*Manager) Release ¶
Release sends a held item on to nodes: those named, or all of the inbox's To when none is. When the inbox names nodes, only those may be chosen; its downloaders are not among them, nor is any such node.
func (*Manager) RemoveDevice ¶
RemoveDevice removes a device: its session ends at its next request.
func (*Manager) RenameNode ¶
RenameNode gives a node another name. What is kept under its name moves with it: where it is drawn, the edges of the nodes that send to it, a template node's templates, a display's devices, enrollment codes and the slips it still shows, an inbox's items it still shows, a sink's documents, a downloader's entries, and the list of the jobs sent to it. An archive keeps writing to the collection it wrote to, and the latest entries it wrote go with it. Where the node is reached changes with it (/ipp/print/<name>, /api/<kind>/<name>, a CUPS server's /printers/<name>); the jobs that reached it keep the name they had. A node with work on its way (deliveries waiting or failed, items held, slips open) is refused, and so is one the manager's options name (on_error).
func (*Manager) Reprint ¶
Reprint sends what a job received again, as a new job of a principal, to a destination: a reprint from the pages. The sender's metadata goes with it.
func (*Manager) ReserveJobNumber ¶
ReserveJobNumber takes the next job number for a job whose document comes later (Input.Number). A number taken and not used is skipped.
func (*Manager) Retry ¶
Retry sends a delivery again now: one waiting for its time, or one that failed for good.
func (*Manager) RotateAppSecret ¶
RotateAppSecret gives an app a new secret, returned once; the old one is refused from now.
func (*Manager) RotateKey ¶
RotateKey gives an uploader a new key, returned once; requests with the old one are refused from now.
func (*Manager) Sender ¶
Sender finds who sends a job with a request (an ingress's, an entry's port's: a CUPS server's IPP): the admin token, a submit token, an app, or, with no SubmitTokens, anyone. ok is false for credentials not known, or none where some are required.
func (*Manager) Session ¶
Session returns the device of a session: one not expired, of a device still enrolled at the same location.
func (*Manager) SlipOfJob ¶
SlipOfJob returns the first slip of a job number: the one at the first location the job reached.
func (*Manager) StoreKey ¶
StoreKey is the same for every manager of a store (New): what a kind keeps in the process for the records of a store (the jobs IPP's Create-Job made, which wait for their documents) is kept by it.
func (*Manager) Submit ¶
Submit takes a document or data for a destination. An entry's settings say what it takes (Accept, Formats) and what it sends on of a document (Output: the .bdf made of it, or the file as received); a template node takes data, a convert node a file as it is, every other node a document made .bdf. What was received is kept once as the job's first payload, and the job is routed from the destination through the topology (route). What the nodes send and make (deliveries, the steps of template and convert nodes) is done after (Tick, or the background). A job the asserts right after the destination refuse is kept, aborted, and the error is a *Refusal (gate).
func (*Manager) Tick ¶
func (m *Manager) Tick(ctx context.Context) (*TickReport, error)
Tick does what is due: it sends the deliveries to printers and archives that wait (or failed and are to be tried again), prints on paper the slips nobody opened in time (or every unopened slip of a display none of whose devices is connected), removes the slips expired, the items ended longer ago than their inbox keeps them, the jobs that ended and nothing shows any more, and the enrollment codes expired. Any instance may call it, at any time, as often as it likes: a scheduler of the platform (every minute), or a timer of the process.
func (*Manager) WritePage ¶
func (m *Manager) WritePage(ctx context.Context, payload string, pages, page, width int, w io.Writer) error
WritePage draws a page (from 0, of pages) of a .bdf payload as PNG, width pixels wide.
func (*Manager) WritePayload ¶
WritePayload writes the bytes of a payload.
type Mark ¶
type Mark struct {
Device string `json:"device,omitempty"`
Worker string `json:"worker,omitempty"`
At time.Time `json:"at"`
}
Mark is who did something to a slip, and when: a device and the worker who said their name there (a record, not an authentication), or the sender ("" device).
type Match ¶
type Match struct {
Name string `json:"name,omitempty"`
User string `json:"user,omitempty"`
Format string `json:"format,omitempty"`
MinPages int `json:"min_pages,omitempty"`
MaxPages int `json:"max_pages,omitempty"`
Meta map[string]string `json:"meta,omitempty"`
Kind string `json:"kind,omitempty"`
}
Match is what a rule looks at; every condition given must hold. Name, User, Format and the values of Meta are regular expressions (RE2), User against the name the sender gave and the verified sender's label, Meta against the job's metadata by key (metaView: the sender's keys, the entry's, the manager's $ keys and the payload's; a key the job lacks does not fit). Kind is the payload's (bdf, data or any).
type Node ¶
type Node struct {
Name string `json:"name"`
Kind string `json:"kind"`
// Title is shown instead of the name; Description is a note of what
// the node is for, shown in the node as the description of a C4
// element is (its first lines on the canvas, all of it beside).
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
// To are the nodes a queue, an uploader or a CUPS server forwards to
// (all of them), the nodes an archive sends on to once it wrote, or
// the nodes an inbox's items may be released to; of a template or a
// convert node, the nodes the document it makes goes to, and Original
// those the payload it took goes to as it was (trace.go).
To []string `json:"to,omitempty"`
Original []string `json:"original,omitempty"`
// Members and Policy are a class's.
Members []string `json:"members,omitempty"`
Policy string `json:"policy,omitempty"`
// Rules and Otherwise are a filter's: the first rule that fits a job
// forwards it; none, Otherwise (empty: the job ends there).
Rules []Rule `json:"rules,omitempty"`
Otherwise []string `json:"otherwise,omitempty"`
// Checks are an assert's: a job must pass every one to go on to To;
// one that does not goes along OnError (assert.go).
Checks []Check `json:"checks,omitempty"`
// Cases and Default are a branch's: the first case whose checks the
// job passes sends it to the case's nodes; none, Default (empty: the
// job ends there).
Cases []Case `json:"cases,omitempty"`
Default []string `json:"default,omitempty"`
// Keep is how long an inbox shows its released and discarded items,
// and a display its slips after they came, opened, done or not
// (default 14 days).
Keep Duration `json:"keep,omitempty"`
// Store is the archive's store, a URL as OpenStore takes for documents
// (bbolt, s3, r2, gcs); Collection the collection (the key prefix)
// its objects are in, "archive-<name>" by default.
Store string `json:"store,omitempty"`
Collection string `json:"collection,omitempty"`
// Accept is what an entry takes: AcceptFile (documents; the default)
// or AcceptData (data for a template node). Output is what it sends
// on of a document: OutputBDF (the .bdf made of it; the default) or
// OutputFile (as received). Formats are the formats it takes, as the
// converter names them (pdf, docx, image, csv … and bdf), of a
// convert node those it converts; none takes any. A document of
// another format is refused (ErrFormat).
Accept string `json:"accept,omitempty"`
Output string `json:"output,omitempty"`
Formats []string `json:"formats,omitempty"`
// Meta is metadata an entry adds to every job it takes in: its keys
// win over the sender's (meta.go).
Meta map[string]any `json:"meta,omitempty"`
// Template is the id of the template a template node fills, or
// TemplateFrom the metadata key whose value names it (a sender's
// "doc_type", say). ListName is the name the data gets when it is a
// list of records (a CSV file, a sheet, a JSON array): the file's name
// by default. Strict refuses data that lacks a name the template
// looks up.
Template string `json:"template,omitempty"`
TemplateFrom string `json:"template_from,omitempty"`
ListName string `json:"list_name,omitempty"`
// SignRole is the role a sign node signs in (RoleWitness when "").
SignRole string `json:"sign_role,omitempty"`
Strict bool `json:"strict,omitempty"`
// KeyHash is the hash of a keyed entry's key (argon2id), never the
// key. Apps are the apps that may send to an entry with their own
// credentials (apps.go), besides the key; that may read a downloader;
// that may work an inbox (inboxapi.go).
KeyHash string `json:"key_hash,omitempty"`
Apps []string `json:"apps,omitempty"`
// Fallback prints a display's slips nobody opened in time, or all of
// them while no device of the display is connected, so that shipping
// does not stop. OfflineAfter is how long a device may be silent and
// still count as connected (default 2 minutes).
Fallback *Fallback `json:"fallback,omitempty"`
OfflineAfter Duration `json:"offline_after,omitempty"`
// URL is a printer's: ipp://, ipps://, socket:// or lpd:// (a printer
// the manager reaches over the network); Route how its jobs reach it
// (direct, branch: docflow/io/ipp). Preview is a printer's fake printer on a
// farm (tools/fakeprinter): the URL of the printer on the farm's API,
// whose pages are shown beside the node (preview.go). Bonjour is the
// instance name a printer's or a CUPS server (sink)'s URL was picked
// by, of what Bonjour (DNS-SD) found on the local links: when that
// address stops answering, the printer is looked for again by it
// (docflow/io/ipp).
URL string `json:"url,omitempty"`
Route string `json:"route,omitempty"`
Preview string `json:"preview,omitempty"`
Bonjour string `json:"bonjour,omitempty"`
// Port is a port of the process's own that a CUPS server (IPP)
// listens on (ports.go); the REST of the other nodes is at the API,
// on the manager's own port. TLSCert and TLSKey are the files of a
// CUPS server's certificate (none: plain ipp). DNSSD false keeps a
// CUPS server's printer off the local links; otherwise it is
// advertised there (Bonjour), as an AirPrint printer computers and
// phones find (Advertised).
Port int `json:"port,omitempty"`
TLSCert string `json:"tls_cert,omitempty"`
TLSKey string `json:"tls_key,omitempty"`
DNSSD *bool `json:"dnssd,omitempty"`
// Latest is how many of the latest documents a sink keeps (default
// 10).
Latest int `json:"latest,omitempty"`
// By, Subject, Fields and Entries are a downloader's: By is the metadata
// key whose value says whose a document is (a customer's id the
// sender gave, say), Subject what of a person is compared with it
// (SubjectEmail, the default, SubjectSub, SubjectID or SubjectGroup),
// Fields the metadata keys copied into the entries listed, and
// Entries how many of the latest entries are listed for one owner,
// and for everyone (default 1000).
By string `json:"by,omitempty"`
Subject string `json:"subject,omitempty"`
Fields []string `json:"fields,omitempty"`
Entries int `json:"entries,omitempty"`
// Scope is who may send to the node from the pages and whose its
// jobs are (ScopeShared, ScopeGroup, ScopePersonal; empty is
// shared), and Owner the group (a value of the IdP's groups claim)
// or the person (ID or email) it belongs to. The jobs sent to a
// group's node are the group's: its members see them.
Scope string `json:"scope,omitempty"`
Owner string `json:"owner,omitempty"`
// OnError are the nodes a job goes to, with the payload that reached
// the node, when the node's send or step fails for good (a notify
// node, say); none, the manager's (Options.OnError), or the job stops
// there, aborted. Every node has them.
OnError []string `json:"on_error,omitempty"`
// Credential names the secret of an exit or a notify node: the
// environment's DOCFLOW_CRED_<name>, or a file (credential.go). It
// is never the secret.
Credential string `json:"credential,omitempty"`
// The settings of the exits and steps of docflow/io and
// docflow/render, which expand {{meta.<key>}} (Out.Expand): Format and
// Page are what a render node makes (pdf, png or svg; the page of a
// png or an svg); From, Recipients and MailSubject a mail's (smtp, and a
// notify node's by mail); Text a mail's text or a notification's;
// Path the key an s3 exit writes; Method and Headers an http exit's
// request, and Body how it carries the document (direct or
// multipart); Via is how a notify node tells (slack, mail or http).
Format string `json:"format,omitempty"`
Page int `json:"page,omitempty"`
From string `json:"from,omitempty"`
Recipients []string `json:"recipients,omitempty"`
MailSubject string `json:"mail_subject,omitempty"`
Text string `json:"text,omitempty"`
Path string `json:"path,omitempty"`
Method string `json:"method,omitempty"`
Headers map[string]string `json:"headers,omitempty"`
Body string `json:"body,omitempty"`
Via string `json:"via,omitempty"`
// Settings are the settings of a kind of its own (one registered
// outside the core and its adapters, with Kind.Fields): an object of
// the kind's fields, checked against them when the node is put
// (fields.go), which the kind reads with SettingsOf. A kind without
// fields has none.
Settings json.RawMessage `json:"settings,omitempty"`
}
Node is a node of the topology, of any kind. Its name is a destination in the one namespace (/in/<name>, a CUPS server's /printers/<name>); the settings are the kind's (PutNode drops the others).
func (*Node) Advertised ¶
Advertised tells a node announced on the local links (Bonjour): one with a port that DNSSD does not keep off.
type OpenAPIOptions ¶
type OpenAPIOptions struct {
// Server is the URL the manager is reached at ("https://docflow.example"),
// the document's server; "" leaves the paths relative.
Server string
// Viewer is who reads it: an app is shown the entries, the inboxes
// and the downloaders that list it, with the scopes to use them; a
// person the downloaders and the inboxes they work; nil, an
// administrator or a person with the role topology, every one.
Viewer *Viewer
// Nodes narrows it to these nodes; none, every one the viewer is
// shown. A node named that is not published to the viewer is
// ErrNotFound.
Nodes []string
}
OpenAPIOptions are what OpenAPI describes.
type Options ¶
type Options struct {
// Converter makes .bdf documents of what senders send (PDF, Office,
// rasters …); nil takes .bdf only.
Converter Converter
// Secret signs the challenges and sessions of devices and the apps'
// tokens: at least 32 random bytes, the same for every instance.
// PreviousSecrets are retired ones, which still open what was signed
// with them while a rotation goes on; nothing is signed with them.
Secret []byte
PreviousSecrets [][]byte
// FontDirs and NoSystemFonts find the fonts of documents, to draw
// their pages and print them.
FontDirs []string
NoSystemFonts bool
// AdminToken authorizes the API (bearer); SubmitTokens are the names
// and secrets that may send jobs (IPP Basic, or bearer name:secret).
// With no SubmitTokens anyone may send.
AdminToken string
SubmitTokens map[string]string
// TickToken authorizes POST /api/tick alone (a scheduler's).
TickToken string
// Viewer returns the person signed in to the pages a request comes
// from (the web application's session), or nil. An admin uses the
// API as the AdminToken does; anyone sees the jobs of their scope and
// sends jobs to the nodes they may send to.
Viewer func(*http.Request) *Viewer
// MaxDocument bounds a document received (default 64 MiB).
MaxDocument int64
// SessionFor is how long a device's session lasts before it signs a
// challenge again (default 10 minutes); SecureCookies sets Secure.
SessionFor time.Duration
SecureCookies bool
// TabletPath is the devices' page, which an enrollment's URL opens
// with ?code= (default /tablet); DeviceOrigin is the origin of that
// URL for the request that made the code (nil: the request's own),
// for an origin the devices reach when the admin's is not one
// (localhost).
TabletPath string
DeviceOrigin func(*http.Request) string
// JobKeep is how long a job that ended stays (its record and, once
// nothing shows it any more, its document): 14 days by default.
JobKeep time.Duration
// Background sends the deliveries of a job (to printers and archives)
// right after it is routed, in a goroutine of the process; without
// it the next Tick does (a function of a serverless platform).
Background bool
// NoPorts refuses nodes with a port of their own (a serverless
// deployment has no listeners of its own); OnChange is called after a
// node is put or deleted, for the process to open and close the ports
// (cmd/docflow).
NoPorts bool
OnChange func()
// Signer is the key that sign nodes sign with (nil: a sign node fails
// its jobs).
Signer *Signer
// TempDir holds documents while they are converted ("" the system's).
TempDir string
// CredentialDir holds the credentials the nodes name, a file each
// (credential.go); the environment's DOCFLOW_CRED_* come first.
CredentialDir string
// OnError are the nodes a job goes to from a send or a step that
// failed for good at a node with no on_error edges of its own (a
// notify node, say); none, the job stops there, aborted.
OnError []string
Log *slog.Logger
// Now is the clock (default time.Now).
Now func() time.Time
}
Options configures a manager.
type Out ¶
type Out struct {
// ID is the delivery's: <job>.<leg>, the same on every try, the key
// a far side tells a second send of the same by (a Message-ID, an
// Idempotency-Key).
ID string
Node *Node
Job *Job
Payload *Payload
// Name is the job's name for the far side (the job's, or the slip's).
Name string
// Meta is the job's metadata, with $error and $error_node when the
// job came along an on_error edge (Cause).
Meta map[string]any
// Cause is the failure that sent the job here along an on_error
// edge, or nil.
Cause *Failure
// Trace is the step the payload came out of, or went into, on its
// way here, or nil ($trace … in Expand).
Trace *Trace
// contains filtered or unexported fields
}
Out is a payload an exit sends out of the topology, or a step takes.
func (*Out) Expand ¶
Expand replaces every {{meta.<key>}} in s with the value of the key (Out.view): a sender's key, name and user, or one of the manager's ($job, $file, $node, $error …); a key not there is empty. There is no other expression.
func (*Out) ExpandFunc ¶
ExpandFunc expands s as Expand does, with every value escaped by esc first (url.QueryEscape, for a URL).
func (*Out) ExpandHeader ¶
ExpandHeader expands s for a header of a mail or a request: without line breaks or other control characters, so that a value cannot add a header.
func (*Out) ExpandPath ¶
ExpandPath expands s for a path (an object's key, a file's name): every value is cleaned of control characters, backslashes and .. segments, and the path of a leading slash, so that a value cannot leave the prefix it is put under.
type Payload ¶
type Payload struct {
ID string `json:"id"`
// Kind is PayloadBDF, PayloadData or PayloadAny; Format the format of
// the bytes (bdf, pdf, csv, json …); Name the file's name, when the
// sender gave one.
Kind string `json:"kind"`
Format string `json:"format,omitempty"`
Name string `json:"name,omitempty"`
// Pages counts the pages of a .bdf document.
Pages int `json:"pages,omitempty"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
// Made is the node that made it ("" for the one received), and At
// when.
Made string `json:"made,omitempty"`
At time.Time `json:"at"`
}
Payload is one of the things a job carries: what was received (a .bdf document, data, or any file), and what the nodes made of it (the .bdf a template or a convert node made). Its bytes are kept under its ID (the job's for the one received, <job>.<leg> for one a node made).
type Person ¶
type Person struct {
Issuer string `json:"iss"`
Subject string `json:"sub"`
Name string `json:"name,omitempty"`
Email string `json:"email,omitempty"`
Groups []string `json:"groups,omitempty"`
// Login is when they last signed in.
Login time.Time `json:"login"`
}
Person is what the web application keeps of a person who signed in: who the IdP said they are, and their groups at the last login.
type PreviewJob ¶
type PreviewJob struct {
ID int32 `json:"id"`
Name string `json:"name,omitempty"`
User string `json:"user,omitempty"`
Format string `json:"format,omitempty"`
State string `json:"state,omitempty"`
Created time.Time `json:"created"`
// Pages counts the pages read back, of the latest job.
Pages int `json:"pages,omitempty"`
}
PreviewJob is a job a fake printer received, as its farm lists it.
type Principal ¶
type Principal struct {
Kind string `json:"kind"`
// ID is the person's (Viewer.ID), the token's or the keyed entry's
// name; empty for an anonymous sender.
ID string `json:"id,omitempty"`
// Name is shown: the person's name or email at the time.
Name string `json:"name,omitempty"`
Via string `json:"via"`
}
Principal is who sent a job, as the manager verified it.
type Printed ¶
type Printed struct {
Printer string `json:"printer"`
Why string `json:"why"` // "fallback" or "device"
Device string `json:"device,omitempty"`
Job int32 `json:"job,omitempty"` // the printer's job id
At time.Time `json:"at"`
}
Printed is a print of a slip on paper.
type Refusal ¶
type Refusal struct {
Job *Job
Failures []CheckFailure
}
Refusal is a job the asserts right after the node it was sent to refused, and the checks it failed there. The job is kept, aborted.
type Release ¶
type Release struct {
To []string `json:"to"`
Worker string `json:"worker,omitempty"`
At time.Time `json:"at"`
}
Release is an item sent on from an inbox.
type Required ¶
Required is a setting a node must have: the JSON key of a field of Node, with a value (not empty), when the settings of If have the values given (a notify node by slack names a credential); always, with no If.
type Role ¶
type Role string
Role is what a kind of node does with a job, as the editor colors it.
const ( // RoleEntry takes jobs from outside the topology and forwards them to // every node of To. RoleEntry Role = "entry" // RoleRoute sends on what reaches it. RoleRoute Role = "route" // RoleStep sends on a payload it makes of what reaches it. RoleStep Role = "step" // RoleExit is where a job ends, or leaves the topology. RoleExit Role = "exit" )
type Signer ¶
type Signer struct {
// Key signs (a key in memory, or one in a KMS behind crypto.Signer),
// and Chain is its certificate followed by those of its chain.
Key crypto.Signer
Chain []*x509.Certificate
// TSA is the URL of a time-stamp authority (RFC 3161) that stamps the
// signatures ("" none).
TSA string
}
Signer is the key that sign nodes sign with (Options.Signer).
type Slip ¶
type Slip struct {
ID string `json:"id"`
Job int32 `json:"job"`
Location string `json:"location"`
Name string `json:"name,omitempty"`
// SubmittedBy and ClaimedUser are the job's.
SubmittedBy *Principal `json:"submitted_by,omitempty"`
ClaimedUser string `json:"claimed_user,omitempty"`
Source string `json:"source"` // "ipp" or "api"
Format string `json:"format,omitempty"`
// Payload is the job's .bdf payload shown here.
Payload string `json:"payload,omitempty"`
Pages int `json:"pages"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
Received time.Time `json:"received"`
// Expires is when the slip leaves the devices, whatever was done to
// it: until then it opens again as often as asked (a canceled one
// does not). It is the display's Keep after the slip came.
Expires time.Time `json:"expires,omitzero"`
State SlipState `json:"state"`
Opened *Mark `json:"opened,omitempty"`
Done *Mark `json:"done,omitempty"`
Canceled *Mark `json:"canceled,omitempty"`
// FallbackAt is when an unopened slip is printed on paper; zero
// when the location has no fallback.
FallbackAt time.Time `json:"fallback_at,omitzero"`
Printed []Printed `json:"printed,omitempty"`
// Lease is held while a manager sends the slip to a printer, so that
// two do not send it at once.
Lease *Lease `json:"lease,omitempty"`
// Attempts, LastError and RetryAt are those of the prints that
// failed.
Attempts int `json:"attempts,omitempty"`
LastError string `json:"last_error,omitempty"`
RetryAt time.Time `json:"retry_at,omitzero"`
}
Slip is a job shown at a display (Location is its name): a document as .bdf, and what happened to it.
type Store ¶
type Store struct {
// database or an object storage, not a file).
Shared bool
// contains filtered or unexported fields
}
Store keeps the records of a manager (nodes, jobs, slips, devices) and the documents of its jobs. Every manager of the same store sees the same state: a manager holds none of its own.
func OpenStore ¶
OpenStore opens the store of the records and the store of the documents, both given as URLs:
bbolt:///var/lib/bdf/docflow.db one file, one process (records and documents) dynamodb://table?region=ap-northeast-1 records only firestore://project/database records only s3://bucket?region=…&endpoint=… records or documents r2://bucket?endpoint=… records or documents gcs://bucket records or documents
documents "" is records when that keeps documents too (bbolt, s3, r2, gcs). The records' store must make writes conditional (yuruidb's ConditionalMutations): a store that cannot is refused.
func (*Store) PruneStates ¶
PruneStates removes up to limit values that expired before a time, and tells how many it removed.
type Template ¶
type Template struct {
ID string `json:"id"`
Node string `json:"node"`
Name string `json:"name,omitempty"`
Format string `json:"format"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
Uploaded time.Time `json:"uploaded"`
Fields []tag.Field `json:"fields"`
// Sample is data the template shows itself filled with, when it
// has some: a start for the data a sender sends.
Sample map[string]any `json:"sample,omitempty"`
}
Template is a template of a template node, which fills it with the data that reaches it: a compiled template (.bdft), or one of Excel, Word, PowerPoint, PDF forms, pdfme or text, as form.Fill takes them. Its id is unique within its node.
type Text ¶
Text is a text in the languages the pages are written in, by language tag (BCP 47: "en", "ja"): English at least, which is read for a language that is not there.
type TickReport ¶
type TickReport struct {
// Delivered and Undelivered count the deliveries to printers and
// archives sent, and the sends that failed (tried again later).
Delivered int `json:"delivered"`
Undelivered int `json:"undelivered"`
// Printed and Failed count the slips printed on paper as a fallback,
// and those that could not be.
Printed int `json:"printed"`
Failed int `json:"failed"`
// Removed, Items and Jobs count the slips expired, and the items and
// the jobs removed after their keep.
Removed int `json:"removed"`
Items int `json:"items"`
Jobs int `json:"jobs"`
Expired int `json:"expired"`
Leased int `json:"leased"`
Location int `json:"locations"`
}
TickReport is what a tick did.
type TopoNode ¶
type TopoNode struct {
Node
// Addresses are where the node is reached, by ingress (ipp: its IPP
// printer's path); API is where the API reaches it (NodePath): a
// keyed entry's, an inbox's, a downloader's.
Addresses map[string]string `json:"addresses,omitempty"`
API string `json:"api,omitempty"`
// Takes is the kind of payload the node takes at its input (bdf,
// data or any), and Emits the kinds it sends on along its edges, as
// inferred from the entries (kinds.go). Accepts are the kinds its
// input may take now: what it takes, within what every node after it
// takes (a queue in front of a printer takes .bdf alone; none: nothing
// fits). Broken are the edges along which the node sends a kind the
// node after it does not take, by the node's name: left by a change
// of settings, drawn broken by the editor, and a job gets a leg of
// the error there.
// Reaches, of a template or a convert node, is the kinds that reach
// it: what it sends on along Original.
Takes string `json:"takes,omitempty"`
Emits []string `json:"emits,omitempty"`
Reaches []string `json:"reaches,omitempty"`
Accepts []string `json:"accepts"`
Broken map[string][]string `json:"broken,omitempty"`
// Templates are the ids of a template node's templates.
Templates []string `json:"templates,omitempty"`
// Held counts the items an inbox holds; Open the slips open at a
// display and Devices its devices; Pending the deliveries waiting at
// a printer, an archive or a class; Kept the jobs a sink keeps, and
// Latest the newest of them; Listed the entries a downloader lists (of
// every owner).
Held int `json:"held,omitempty"`
Open int `json:"open,omitempty"`
Devices int `json:"devices,omitempty"`
Pending int `json:"pending,omitempty"`
Kept int `json:"kept,omitempty"`
Latest string `json:"latest,omitempty"`
Listed int `json:"listed,omitempty"`
}
TopoNode is a node of the topology as the API shows it: the node (its key's hash left out) and what is at it now.
type Trace ¶
type Trace struct {
// ID is the step's: the id of its delivery, unique to it.
ID string `json:"id"`
// Node is the template or convert node that did the step, Kind its
// kind.
Node string `json:"node"`
Kind string `json:"kind"`
// Role is the side of the payload this trace goes with: TraceSource
// or TraceOutput.
Role string `json:"role"`
Source TraceSide `json:"source"`
Output TraceSide `json:"output"`
// Fingerprints are the steps of the payload's lineage, oldest first:
// those of the trace the payload took had, then this one's.
Fingerprints []Fingerprint `json:"fingerprints"`
}
Trace ties the payloads a step took and made.
type TraceSide ¶
type TraceSide struct {
Payload string `json:"payload"`
Kind string `json:"kind"`
Format string `json:"format,omitempty"`
Name string `json:"name,omitempty"`
SHA256 string `json:"sha256"`
Key string `json:"key"`
Object string `json:"object"`
}
TraceSide is a payload of a step, and how an archive names it: Key is the key of its objects (the record is Key + ".json"), Object its file.
type Viewer ¶
type Viewer struct {
// Kind and Via are as a Principal's (PrincipalUser and ViaOIDC for a
// person).
Kind string
Via string
// ID is stable for the person (the web application derives it from
// the IdP's issuer and subject), or the token's name.
ID string
Name string
Email string
// Groups are the values of the IdP's groups claim at the last login.
Groups []string
// Subject is the person's subject at the IdP (sub), when the web
// application knows it: what a downloader compares with a document's
// owner under SubjectSub.
Subject string
// Scopes are an app's (granted to its token), or a person's token's.
Scopes []string
// Roles are a person's (RoleTopology, RoleAudit).
Roles []string
// Admin sees everything and changes the settings.
Admin bool
}
Viewer is whoever a request is from: a person signed in to the pages, or a token.
func (*Viewer) CanCancel ¶
CanCancel tells whether the viewer may cancel a job: its submitter (an app with the scope) and the admins (the members of its group only see it).
func (*Viewer) CanSee ¶
CanSee tells whether the viewer may see a job: its submitter, the members of its group, the auditors and the admins.
func (*Viewer) CanSendTo ¶
CanSendTo tells whether the viewer may send to a node of a scope and owner from the pages.
Source Files
¶
- apps.go
- archived.go
- assert.go
- branch.go
- credential.go
- deliver.go
- devices.go
- download.go
- fields.go
- filter.go
- http.go
- inbox.go
- inboxapi.go
- kind.go
- kinds.go
- kinds_core.go
- live.go
- manager.go
- meta.go
- model.go
- nodes.go
- oauth.go
- openapi.go
- people.go
- ports.go
- preview.go
- rename.go
- route.go
- scope.go
- send.go
- signnode.go
- sink.go
- store.go
- submit.go
- trace.go
- transform.go
- upload.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package flowtest is what the tests of the adapters of docflow share: a manager over a store of a temporary directory, served over HTTP, with a clock of its own, and the far sides an exit sends to, in the process (an SMTP server, a web hook).
|
Package flowtest is what the tests of the adapters of docflow share: a manager over a store of a temporary directory, served over HTTP, with a clock of its own, and the far sides an exit sends to, in the process (an SMTP server, a web hook). |
|
io
|
|
|
all
Package all imports every input and output of docflow, and its render node, so that a program that serves them all imports this package alone: the IPP printers and CUPS servers (docflow/io/ipp), mail (docflow/io/smtp), S3 and its trigger (docflow/io/s3), HTTP (docflow/io/http), the notify node (docflow/io/notify) and the render node (docflow/render).
|
Package all imports every input and output of docflow, and its render node, so that a program that serves them all imports this package alone: the IPP printers and CUPS servers (docflow/io/ipp), mail (docflow/io/smtp), S3 and its trigger (docflow/io/s3), HTTP (docflow/io/http), the notify node (docflow/io/notify) and the render node (docflow/render). |
|
http
Package http is the HTTP output of docflow: the kind http, shown as HTTP (push), sends what reaches the node to a web service in a request (a downloader is where applications fetch documents instead).
|
Package http is the HTTP output of docflow: the kind http, shown as HTTP (push), sends what reaches the node to a web service in a request (a downloader is where applications fetch documents instead). |
|
ipp
Package ipp is the IPP input and output of docflow: the printers a job is printed on (the kind printer, over IPP, port 9100 or LPD), the CUPS servers jobs are printed to (the kind cups, an entry: a source), and the queues of CUPS servers jobs are printed on (the kind cups-out, an exit: a sink), as docflow's kinds of node are registered.
|
Package ipp is the IPP input and output of docflow: the printers a job is printed on (the kind printer, over IPP, port 9100 or LPD), the CUPS servers jobs are printed to (the kind cups, an entry: a source), and the queues of CUPS servers jobs are printed on (the kind cups-out, an exit: a sink), as docflow's kinds of node are registered. |
|
notify
Package notify is the notify node of docflow: it tells that a job passed it, to Slack (an incoming webhook), by mail, or to a webhook of one's own (http), and sends the job on along its To, if any, with what reached it.
|
Package notify is the notify node of docflow: it tells that a job passed it, to Slack (an incoming webhook), by mail, or to a webhook of one's own (http), and sends the job on along its To, if any, with what reached it. |
|
s3
Package s3 is the S3 input and output of docflow: the kind s3 writes what reaches the node to a bucket (an exit), and the kind s3-trigger takes the objects an S3 event names (an entry).
|
Package s3 is the S3 input and output of docflow: the kind s3 writes what reaches the node to a bucket (an exit), and the kind s3-trigger takes the objects an S3 event names (an entry). |
|
smtp
Package smtp is the mail output of docflow: the kind smtp sends what reaches the node as the attachment of a mail, over SMTP (net/smtp).
|
Package smtp is the mail output of docflow: the kind smtp sends what reaches the node as the attachment of a mail, over SMTP (net/smtp). |
|
Package render is the render node of docflow: it draws the .bdf document that reaches it as a PDF file (vector/pdfbdf), or a page of it as a PNG image (raster/imagebdf), for an exit whose far side has no viewer of BDF (a mail's reader, a web service).
|
Package render is the render node of docflow: it draws the .bdf document that reaches it as a PDF file (vector/pdfbdf), or a page of it as a PNG image (raster/imagebdf), for an exit whose far side has no viewer of BDF (a mail's reader, a web service). |
|
help
Package help is Docflow's manual: chapters written in Markdown beside this file, in English (en) and Japanese (ja), embedded in the binary and served by the web application at /help for everyone signed in.
|
Package help is Docflow's manual: chapters written in Markdown beside this file, in English (en) and Japanese (ja), embedded in the binary and served by the web application at /help for everyone signed in. |
|
Package webmessages is the catalog of the texts of Docflow's pages, in English and Japanese: pages.yaml, compiled by pw generate into messages_pw_gen.go, which the templates of docflow/web call with the locale of the request (popcornweb.toml's [i18n]).
|
Package webmessages is the catalog of the texts of Docflow's pages, in English and Japanese: pages.yaml, compiled by pw generate into messages_pw_gen.go, which the templates of docflow/web call with the locale of the request (popcornweb.toml's [i18n]). |