wire

package module
v0.0.0-...-343dfa7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 4 Imported by: 0

README

go-wire

go-wire provides explicit, auditable JSON, XML, SOAP, YAML, TOML, MessagePack, CBOR, and BSON interoperability boundaries with bounded read and write APIs.

Status

The package is pre-v1. Supported format behavior is fixture-backed, fuzzed, benchmarked, and held to meaningful 100% production coverage.

Requirements

  • Go 1.25 or later

Installation

go get github.com/faustbrian/go-wire

Import format packages explicitly, such as github.com/faustbrian/go-wire/jsonwire or github.com/faustbrian/go-wire/soap.

Quickstart

var response struct {
    Status string `json:"status"`
}

err := jsonwire.DecodeReader(
    strings.NewReader(`{"status":"ok"}`),
    &response,
    jsonwire.DecodeOptions{DisallowUnknownFields: true},
)
if err != nil {
    return err
}

Each format exposes explicit options and limits. See the quickstart for XML namespace validation, SOAP envelopes, and binary-format examples.

Package Guarantees

  • bounded decode and encode paths for every supported format
  • explicit format packages instead of a lossy universal codec
  • deterministic output where the format and selected mode permit it
  • stable error classification and strict defaults
  • documented charset, depth, collection, extension, and data-shape limits
  • no HTTP policy, WSDL, schema engine, persistence, or application mapping

The format matrix is authoritative for supported and intentionally unsupported behavior.

Documentation

Start with the documentation index, quickstart, adoption guide, and API reference. Review dependencies, evidence, and hardening before processing hostile input.

AI tools can use llms.txt and llms-full.txt. Release history is maintained in CHANGELOG.md.

Development

Run make check before submitting a change. This enforces formatting, static analysis, race tests, meaningful 100% coverage, format fuzz smoke, benchmarks, documentation, and vulnerability scanning.

Contributing

Read CONTRIBUTING.md and follow the code of conduct. Format-specific behavior and interoperability tradeoffs must be documented explicitly.

Security

Report vulnerabilities privately according to SECURITY.md. Review docs/security.md before decoding untrusted payloads.

License

go-wire is available under the MIT License. Attribution and third-party policy are recorded in NOTICE and THIRD_PARTY_NOTICES.md.

Documentation

Overview

Package wire provides shared format and error primitives for structured wire-format packages.

Format-specific behavior lives in the jsonwire, xmlwire, soap, yamlwire, tomlwire, msgpackwire, cborwire, and bsonwire packages. Detection is deliberately limited to opt-in JSON/XML inspection because callers at interoperability boundaries usually know which wire format a peer promises to send.

Example (BsonRoundTrip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/bsonwire"
)

func main() {
	value := bsonwire.D{{Key: "status", Value: "ok"}}
	var output bytes.Buffer
	if err := bsonwire.EncodeWriter(&output, value, bsonwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	var decoded bsonwire.M
	if err := bsonwire.Decode(output.Bytes(), &decoded, bsonwire.DecodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(decoded["status"])
}

Output:
ok
Example (CborRoundTrip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/cborwire"
)

func main() {
	value := struct {
		Status string `cbor:"status"`
	}{Status: "ok"}
	var output bytes.Buffer
	if err := cborwire.EncodeWriter(&output, value, cborwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	var decoded struct {
		Status string `cbor:"status"`
	}
	if err := cborwire.Decode(output.Bytes(), &decoded, cborwire.DecodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(decoded.Status)
}

Output:
ok
Example (Json) 
package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/faustbrian/go-wire/jsonwire"
)

func main() {
	var response struct {
		Status string `json:"status"`
	}
	err := jsonwire.DecodeReader(
		strings.NewReader(`{"status":"ok"}`),
		&response,
		jsonwire.DecodeOptions{DisallowUnknownFields: true},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Status)
}

Output:
ok
Example (JsonWriter) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/jsonwire"
)

func main() {
	var output bytes.Buffer
	err := jsonwire.EncodeWriter(&output, map[string]int{"z": 2, "a": 1}, jsonwire.EncodeOptions{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(output.String())
}

Output:
{"a":1,"z":2}
Example (MessagePackRoundTrip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/msgpackwire"
)

func main() {
	value := struct {
		Status string `msgpack:"status"`
	}{Status: "ok"}
	var output bytes.Buffer
	if err := msgpackwire.EncodeWriter(&output, value, msgpackwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	var decoded struct {
		Status string `msgpack:"status"`
	}
	if err := msgpackwire.Decode(output.Bytes(), &decoded, msgpackwire.DecodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(decoded.Status)
}

Output:
ok
Example (SoapFault) 
package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire"
	"github.com/faustbrian/go-wire/soap"
)

func main() {
	payload, err := soap.MarshalFault(soap.Fault{
		Version: soap.Version11,
		Code:    "soap:Server",
		Reason:  "Carrier unavailable",
	})
	if err != nil {
		log.Fatal(err)
	}
	_, err = soap.Parse(payload, soap.ParseOptions{})
	if errors.Is(err, wire.ErrSOAPFault) {
		fmt.Println("fault")
	}
}

Output:
fault
Example (SoapWriter) 
package main

import (
	"bytes"
	"encoding/xml"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/soap"
)

func main() {
	var output bytes.Buffer
	request := struct {
		XMLName xml.Name `xml:"Ping"`
	}{}
	if err := soap.EncodeWriter(&output, soap.Version11, nil, request, soap.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(output.String())
}

Output:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><Ping></Ping></soap:Body></soap:Envelope>
Example (TomlRoundTrip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/tomlwire"
)

func main() {
	value := struct {
		Status string `toml:"status"`
	}{Status: "ok"}
	var output bytes.Buffer
	if err := tomlwire.EncodeWriter(&output, value, tomlwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	var decoded struct {
		Status string `toml:"status"`
	}
	if err := tomlwire.Decode(output.Bytes(), &decoded, tomlwire.DecodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(decoded.Status)
}

Output:
ok
Example (Xml) 
package main

import (
	"encoding/xml"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/xmlwire"
)

func main() {
	var shipment struct {
		XMLName xml.Name `xml:"urn:vendor Shipment"`
		ID      int      `xml:"urn:vendor ID"`
	}
	payload := []byte(`<v:Shipment xmlns:v="urn:vendor"><v:ID>42</v:ID></v:Shipment>`)
	err := xmlwire.Decode(payload, &shipment, xmlwire.DecodeOptions{
		ExpectedRoot: xml.Name{Space: "urn:vendor", Local: "Shipment"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(shipment.ID)
}

Output:
42
Example (XmlWriter) 
package main

import (
	"bytes"
	"encoding/xml"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/xmlwire"
)

func main() {
	var output bytes.Buffer
	value := struct {
		XMLName xml.Name `xml:"Status"`
		Value   string   `xml:",chardata"`
	}{Value: "ok"}
	if err := xmlwire.EncodeWriter(&output, value, xmlwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(output.String())
}

Output:
<Status>ok</Status>
Example (YamlRoundTrip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/faustbrian/go-wire/yamlwire"
)

func main() {
	value := struct {
		Status string `yaml:"status"`
	}{Status: "ok"}
	var output bytes.Buffer
	if err := yamlwire.EncodeWriter(&output, value, yamlwire.EncodeOptions{}); err != nil {
		log.Fatal(err)
	}
	var decoded struct {
		Status string `yaml:"status"`
	}
	if err := yamlwire.Decode(output.Bytes(), &decoded, yamlwire.DecodeOptions{}); err != nil {
		log.Fatal(err)
	}
	fmt.Println(decoded.Status)
}

Output:
ok

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrParse             = errors.New("parse failure")
	ErrValidation        = errors.New("validation failure")
	ErrUnsupportedFormat = errors.New("unsupported format")
	ErrEnvelope          = errors.New("envelope failure")
	ErrSOAPFault         = errors.New("SOAP fault")
	ErrWrite             = errors.New("write failure")
	ErrSizeLimit         = errors.New("size limit exceeded")
	ErrTarget            = errors.New("invalid target")
	ErrEncode            = errors.New("encode failure")
)

Functions

This section is empty.

Types

type Error 

type Error struct {
	Kind   ErrorKind
	Format Format
	Op     string
	Err    error
}

Error describes a wire-format operation failure.

func (*Error) Error 

func (e *Error) Error() string

Error returns a stable, human-readable description of the failure.

func (*Error) Is 

func (e *Error) Is(target error) bool

Is reports whether target is the sentinel associated with the error kind or matches the underlying cause.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the underlying format-specific failure, if any.

type ErrorKind 

type ErrorKind string

ErrorKind classifies a failure independently of its underlying cause. 

const (
	ErrorKindParse       ErrorKind = "parse"
	ErrorKindValidation  ErrorKind = "validation"
	ErrorKindUnsupported ErrorKind = "unsupported"
	ErrorKindEnvelope    ErrorKind = "envelope"
	ErrorKindFault       ErrorKind = "fault"
	ErrorKindWrite       ErrorKind = "write"
	ErrorKindSizeLimit   ErrorKind = "size-limit"
	ErrorKindTarget      ErrorKind = "target"
	ErrorKindEncode      ErrorKind = "encode"
)

type Format 

type Format string

Format identifies a supported structured wire format. 

const (
	FormatJSON Format = "json"
	FormatXML  Format = "xml"
	FormatSOAP Format = "soap"
	FormatYAML Format = "yaml"
	FormatTOML Format = "toml"
	// FormatMessagePack names the MessagePack binary format.
	FormatMessagePack Format = "msgpack"
	FormatCBOR        Format = "cbor"
	FormatBSON        Format = "bson"
)

func DetectFormat 

func DetectFormat(payload []byte) (Format, error)

DetectFormat distinguishes JSON from XML using the first significant byte. SOAP is returned as XML because reliably identifying a SOAP envelope requires parsing its namespace; use the soap package when SOAP is expected.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/faustbrian/go-wire"
)

func main() {
	format, err := wire.DetectFormat([]byte(`{"status":"ok"}`))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(format)
}

Output:
json

Source Files

View all Source files

Directories

Path Synopsis
Package bsonwire provides bounded BSON document decoding and encoding.
 Package bsonwire provides bounded BSON document decoding and encoding.
Package cborwire provides bounded CBOR decoding and deterministic encoding.
 Package cborwire provides bounded CBOR decoding and deterministic encoding.
cmd
semvercheck command
internal
outputlimit
Package outputlimit provides bounded in-memory encoding destinations.
 Package outputlimit provides bounded in-memory encoding destinations.
semver
valuecheck
Package valuecheck validates reflection values before recursive encoding.
 Package valuecheck validates reflection values before recursive encoding.
Package jsonwire provides bounded, strict JSON helpers for interoperability boundaries where encoding/json's low-level defaults need explicit policy.
 Package jsonwire provides bounded, strict JSON helpers for interoperability boundaries where encoding/json's low-level defaults need explicit policy.
Package msgpackwire provides bounded MessagePack decoding and deterministic encoding.
 Package msgpackwire provides bounded MessagePack decoding and deterministic encoding.
Package soap provides transport-neutral SOAP 1.1 and SOAP 1.2 envelope, body, and fault primitives while preserving access to the original XML.
 Package soap provides transport-neutral SOAP 1.1 and SOAP 1.2 envelope, body, and fault primitives while preserving access to the original XML.
Package tomlwire provides bounded, strict TOML document decoding and deterministic encoding.
 Package tomlwire provides bounded, strict TOML document decoding and deterministic encoding.
Package xmlwire provides bounded XML encoding and decoding with explicit namespace, root-element, strictness, and character-set policy.
 Package xmlwire provides bounded XML encoding and decoding with explicit namespace, root-element, strictness, and character-set policy.
Package yamlwire provides bounded, explicit YAML 1.2 decoding and deterministic encoding.
 Package yamlwire provides bounded, explicit YAML 1.2 decoding and deterministic encoding.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.