Public Go API Surface#

opnDossier ships as both a CLI binary and a reusable Go library. This document defines which packages under pkg/ are part of the public API, what stability guarantees apply, and what constitutes a breaking change.

See README.md § Using as a Go Library for import examples and the quick-start consumer flow.

Current Regime#

This policy takes effect starting with v1.5. Releases prior to v1.5 made no public-API semver commitment on pkg/ shape. For v1.4 and earlier, treat pkg/ as subject to change between any two releases.

Package Classification#

The module path is github.com/EvilBit-Labs/opnDossier.

Public API (stability-tracked)#

These packages are intended for direct consumption by other Go modules. Their exported identifiers follow the stability rules in the next section.

Idiomatic consumer entry point#

opnsense.ConvertDocument(*schema.OpnSenseDocument) and pfsense.ConvertDocument(*pfschema.Document) are the idiomatic, primary public-API entry points for Go consumers that already have a parsed vendor DTO. Parse the XML once (with encoding/xml, parser.NewSecureXMLDecoder, or your own decoder), then call ConvertDocument as many times as you need. No blank imports required — the caller references the concrete package directly, so the registry is not involved.

The pfschema alias in the signature above disambiguates the schema package (pkg/schema/pfsense) from the parser package (pkg/parser/pfsense) — both are named pfsense on disk, so a real consumer importing both must alias one. The OPNsense side has the same collision but uses the long-standing convention of importing pkg/schema/opnsense as schema.

parser.Factory.CreateDevice(ctx, reader, deviceTypeOverride, validateMode) is the auto-detection escape hatch — the path you use when you have a reader but no pre-parsed DTO. The factory peeks the XML root element, dispatches to the registered parser for that device type, and returns a converted CommonDevice. Factory is stable and covered by the same semver commitments as the rest of pkg/parser, but consumers should treat it as a convenience wrapper over ConvertDocument rather than the canonical entry point. Auto-detection requires blank imports of the device parser packages so their init() functions can self-register (see Registration Contract).

Error-semantics difference#

The two paths surface different errors for related failure modes:

Consumers that already have a DTO in hand should call ConvertDocument and handle errors.Is(err, ErrNilDocument) explicitly. Consumers that receive raw XML from a reader should call Factory.CreateDevice and handle errors.Is(err, parser.ErrUnsupportedCharset) for an unreadable encoding, plus the "unsupported device type" and "ensure parser packages are imported" strings for the dispatch failures. Prefer the sentinel over string matching wherever one exists — the message text is not part of the semver contract.

Public but vendor-tracking#

These packages expose XML data transfer objects that mirror OPNsense and pfSense on-disk formats. They are importable and useful — for example, config generators or schema-aware tooling need the exact XML shape — but they track the upstream firewall schema, so field changes follow OPNsense/pfSense releases rather than opnDossier's own cadence.

Analyzers and auditors should prefer pkg/model.CommonDevice — it is stable across firewall schema drift. Generators, linters, and tooling that must emit or inspect exact XML structure should use pkg/schema/* directly and accept that the shape follows the vendor.

Not public API#

Everything under cmd/ and internal/ is implementation detail. This includes internal/cfgparser, internal/converter, internal/sanitizer, internal/validator, internal/diff, and all compliance plugins. These can change or disappear without notice, and Go's internal/ enforcement prevents direct import regardless.

Stability Policy#

Pre-v1.0.0#

Until the first tagged v1.0.0 release, the public API is considered beta. Minor versions (v0.X.0) may contain breaking changes. We still try hard not to break consumers within a single minor line — in practice, breaking changes are batched into minor bumps with migration notes in CHANGELOG.md — but the semver contract is not yet formal.

Pin a specific version in your go.mod and read release notes before upgrading.

Post-v1.0.0#

Once v1.0.0 is tagged, the public API follows semantic versioning:

• Patch (v1.2.X): bug fixes and internal changes. No public API changes.
• Minor (v1.X.0): new exported symbols, new fields on existing structs, new Severity constants, new device types in the parser registry. Existing consumers must continue to compile and behave correctly.
• Major (v2.0.0): breaking changes, batched and documented in CHANGELOG.md with a migration guide.

What counts as a breaking change#

Within the public API packages, these changes require a major version bump:

• Removing or renaming an exported type, function, method, field, constant, or variable.
• Changing the signature of an exported function or method (adding a parameter, changing a return type, reordering arguments).
• Changing the type of an exported field.
• Changing the semantics of an existing function so that correct callers would now misbehave.
• Changing the value of an exported constant that callers might compare against (e.g., renaming SeverityHigh = "high" to "HIGH").
• Tightening an interface by adding a method (existing implementations would no longer satisfy it).

These changes are not breaking and may appear in minor releases:

• Adding a new exported type, function, method, or constant.
• Adding a new field to a struct (consumers using struct literals without field names will break, but that is their bug — we never promise positional struct literal stability).
• Adding a new Severity constant. Consumers that switch on severity without a default clause should add one.
• Adding a new device type to the parser registry.
• Adding new fields to ConversionWarning.
• Widening an accepted input set (e.g., parsing previously-rejected XML).

CommonDevice specifically#

pkg/model.CommonDevice is the primary consumer contract. We commit to:

• Never removing a top-level field without a deprecation cycle spanning at least one minor release.
• Keeping DeviceType, Severity, and the exported ConversionWarning shape stable across minor releases.
• Adding new fields in minor releases when we grow support for additional device subsystems. Consumers should not assume the struct is closed.

Fields may be populated more completely over time — for example, a subsystem that currently emits empty slices may begin emitting data as new converter work lands. This is not a breaking change.

ConversionWarning#

ConversionWarning is append-only. New severities may be added in minor releases. The Field, Value, Message, and Severity fields will not be removed or repurposed. Warning text is not part of the contract — log it, do not match on it.

Registration Contract (blank imports)#

pkg/parser.Factory.CreateDevice dispatches through the global DeviceParserRegistry. Device parsers self-register from their init() function, which Go only runs when the package is imported. Consumers that want auto-detection through the factory must add blank imports:

import (
    "github.com/EvilBit-Labs/opnDossier/pkg/parser"

    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/opnsense" // registers "opnsense"
    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/pfsense" // registers "pfsense"
)

When the registry is empty, Factory.CreateDevice returns an error whose text contains the substring "ensure parser packages are imported". That substring is covered by a regression test and is safe for tooling to match on. The full wording may change — the hint substring will not.

Consumers who bypass the factory and call pkg/parser/opnsense.ConvertDocument or pkg/parser/pfsense.ConvertDocument directly do not need the blank import, because they reference the package by name.

CLI-Only Dependency Isolation#

pkg/ packages must not import CLI-only dependencies. As of this writing, that means no transitive dependency on:

• github.com/spf13/cobra and github.com/spf13/viper
• github.com/charmbracelet/glamour, lipgloss
• github.com/alecthomas/chroma
• github.com/olekukonko/tablewriter
• github.com/muesli/reflow

Any PR that introduces a CLI-only import into a public pkg/ package is a breaking change against the consumer contract — it will pull those deps into every downstream go.sum. Reviewers should reject such changes.

opnConfigGenerator maintains a TestConsumerDependencyIsolation test that runs go list -deps and fails if any of the packages above leak. If that test breaks after an opnDossier upgrade, the leak is in pkg/, not in the consumer.

Handling Secrets in CommonDevice#

CommonDevice carries plaintext secrets (certificate private keys, pre-shared keys, API tokens, SNMP community strings, HA sync passwords, DHCPv6 key material). opnDossier does not export a public redaction helper in pkg/ — the sanitizer and export-redaction code paths live in internal/ and are wired through the CLI.

Consumers who serialize CommonDevice to JSON, YAML, or any other format must redact these fields themselves. See the README § Handling Secrets for recommended patterns (subprocess invocation, in-place redaction, custom json.Marshaler).

The secret-bearing fields on CommonDevice are:

If you add a new secret-bearing field to CommonDevice, update this table in the same PR.

Notes on fields that are not in this table:

• OpenVPN TLS auth / static-key material (raw XML fields on the OPNsense/pfSense schema types) is dropped by the converter and never appears on CommonDevice — it can only leak via the raw-XML sanitize path (see internal/sanitizer rules, which the CLI applies). Library consumers that work exclusively with CommonDevice cannot accidentally emit OpenVPN TLS key material.
• model.IPsecConfig.KeyPairs and model.IPsecConfig.PreSharedKeys currently carry UUID references to the OPNsense Ipsec/KeyPairs and Ipsec/PreSharedKey MVC models, not raw key material. They are intentionally omitted from the table above. If a future OPNsense schema revision ever stores raw key bytes in these fields, they must be added here and to the CLI redaction logic in the same PR.
• pfSense IPsecPhase1.PreSharedKey (a scalar raw key on the pfSense XML schema) is intentionally not mapped into model.IPsecPhase1Tunnel; see pkg/parser/pfsense/converter_services.go and the TestConverter_IPsecPhase1_PreSharedKeyExclusion regression test.

API Shape Enforcement#

The stability commitments above are enforced by two mechanisms in addition to human review:

Compile-time interface assertions#

pkg/parser/api_shape_test.go contains var _ Interface = (*Impl)(nil) assertions for every public interface / concrete-type pair in pkg/parser, pkg/parser/opnsense, and pkg/parser/pfsense. Removing a method from an interface, or changing a method signature on a concrete type so it no longer satisfies the interface, breaks the build immediately — before any test runs. Extend this file whenever a new public implementation / interface pair lands.

API snapshot tests (goldie)#

pkg/parser/api_snapshot_test.go captures the full go doc -all output of each public package into a golden fixture under pkg/parser/testdata/api-snapshots/:

• pkg-parser.golden — go doc -all ./pkg/parser
• pkg-parser-opnsense.golden — go doc -all ./pkg/parser/opnsense
• pkg-parser-pfsense.golden — go doc -all ./pkg/parser/pfsense
• pkg-model.golden — go doc -all ./pkg/model
• pkg-schema-opnsense.golden — go doc -all ./pkg/schema/opnsense
• pkg-schema-pfsense.golden — go doc -all ./pkg/schema/pfsense
• pkg-schema-shared.golden — go doc -all ./pkg/schema/shared

Any accidental change to the public surface — a renamed type, a new exported method, a rewritten doc comment, a deleted constant — shows up as a diff in one of these fixtures during code review. This is the authoritative baseline for v1.5 and forward.

When an intentional API change lands, regenerate the fixtures:

go test ./pkg/parser/... -run TestPublicAPISnapshot -update

Then review the diff carefully — everything new in a pkg-parser-* or pkg-model snapshot becomes a stability commitment. The three pkg-schema-* fixtures are the exception: pkg/schema/* is public but vendor-tracking (see above), so a diff there is not a semver commitment. Those fixtures exist so that a field removed or a serialization tag changed to follow the vendor's config.xml is visible in review rather than silent, and any PR that touches pkg/schema/* must regenerate them. The release checklist in RELEASING.md requires a snapshot diff review before any tag is pushed.

Packages outside pkg/ (everything under cmd/ and internal/) are not snapshot-tracked; they can change without regeneration.

Revision History#

Every change to this document must add a row to the Revision History table with date (YYYY-MM-DD) and a one-line description.