Documentation
¶
Overview ¶
Package plugin defines the public protocol for convertr external plugins.
A plugin is an executable named convertr-<NAME> that implements two sub-commands:
convertr-NAME capabilities
Writes a JSON array of Capability objects to stdout and exits 0.
convertr-NAME convert --from FROM --to TO --input IN --output OUT [--opt key=value ...]
Converts IN to OUT. Exits 0 on success, non-zero on failure.
On failure, writes a single line error message to stderr.
Protocol versions:
v1: a bare JSON array of {from, to, cost} objects.
v2: a JSON envelope {protocol_version:2, version:"...", diagnostics:[...], capabilities:[...], operations:[...]}.
Use ParseCapabilities to transparently handle both versions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capability ¶
type Capability struct {
From string `json:"from"` // source format ID (e.g. "md")
To string `json:"to"` // target format ID (e.g. "html")
Cost int `json:"cost"` // routing cost (1–10; lower = preferred)
}
Capability describes one conversion edge a plugin can perform. This type is stable and used in both v1 and v2 protocols.
type Diagnostic ¶ added in v0.1.1
type Diagnostic struct {
// Level is a stable severity string such as "info", "warning", or "error".
Level string `json:"level"`
// Code is an optional stable machine-readable diagnostic identifier.
Code string `json:"code,omitempty"`
// Message is a human-readable diagnostic message.
Message string `json:"message"`
}
Diagnostic describes manifest-level plugin status information. Diagnostics are advisory metadata for users and discovery tooling; they do not make an otherwise valid manifest fail parsing.
type Manifest ¶ added in v0.1.1
type Manifest struct {
// ProtocolVersion is 1 for bare array input, 2 for envelope input.
ProtocolVersion int `json:"protocol_version"`
// Version is the optional plugin version advertised by v2 manifests.
Version string `json:"version,omitempty"`
// Diagnostics are optional manifest-level status messages advertised by v2.
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
Capabilities []V2Capability `json:"capabilities"`
Operations []Operation `json:"operations,omitempty"`
}
Manifest is the v2 protocol envelope. When protocol_version is 1, only Capabilities is populated (from a bare JSON array).
func ParseCapabilities ¶ added in v0.1.1
ParseCapabilities parses plugin capabilities output in either v1 (bare array) or v2 (envelope) format. It returns a Manifest regardless of the input version.
type Operation ¶ added in v0.1.1
type Operation struct {
// Name is the operation identifier (e.g. "pdf.merge").
Name string `json:"name"`
// Description is an optional human-readable description.
Description string `json:"description,omitempty"`
// Params describes accepted parameters as name→description pairs.
Params map[string]string `json:"params,omitempty"`
}
Operation describes a processor operation that a plugin supports. Only valid in protocol version 2+.
type V2Capability ¶ added in v0.1.1
type V2Capability struct {
Capability
// Quality is an optional quality hint (0–100). nil when not specified.
Quality *int `json:"quality,omitempty"`
// Lossy indicates whether the conversion is lossy. nil when not specified.
Lossy *bool `json:"lossy,omitempty"`
// Metadata holds arbitrary key-value pairs for extra information about
// this conversion edge. nil when not specified.
Metadata map[string]string `json:"metadata,omitempty"`
}
V2Capability extends Capability with optional quality, lossy, and metadata fields available in protocol version 2.
Source Files