mediatyper

Documentation

Overview

Package mediatyper parses and formats HTTP media type strings of the form type/subtype+suffix; params. It is a port of the npm media-typer package (the small module used internally by Express and the wider connect/body middleware ecosystem) implemented with nothing beyond the Go standard library. Media types are the "content" identifiers carried in headers such as Content-Type and Accept, and this package gives you a structured, round-trippable representation of them following the grammar in RFC 6838 and the token/quoted-string rules of RFC 7231/7230.

You reach for this package whenever you need to inspect or rewrite a media type rather than merely compare it as an opaque string. Typical uses are splitting "application/vnd.api+json; charset=utf-8" into its top-level type, its subtype, its structured "+json" suffix and its parameters, or building such a string back up from those pieces so that it is guaranteed to be well formed. Because it only manipulates syntax it performs no I/O, keeps no state, and is safe for concurrent use.

The two entry points are Parse and Format. Parse takes a string and returns a MediaType whose Type, Subtype, Suffix and Parameters fields are filled in; the type, subtype and suffix are lower-cased, parameter names are lower-cased keys, and quoted parameter values are unescaped so you see the logical value. Format is the inverse: given a MediaType it validates that the type, subtype, suffix and parameter names are legal RFC 7230 tokens, lower-cases them, quotes any parameter value that is not a bare token, and emits parameters in a stable sorted order so the output is deterministic.

Several edge cases are worth calling out. Empty or whitespace-only input, a head with no "/" separator, an invalid type, subtype or suffix, a parameter missing its "=" value, or a value that is neither a valid token nor a proper quoted-string all cause Parse to return an error rather than a partial result. A subtype is split on its last "+" so that only the trailing segment becomes the Suffix ("vnd.api+json" yields subtype "vnd.api", suffix "json"). Format likewise rejects a MediaType whose components are not valid tokens, so a value produced by Parse can always be re-formatted, and a value you build by hand is checked before it is emitted.

Compared with the Node original the behavior is intentionally close: the same split into type, subtype, suffix and parameters, the same case normalization, and the same quoting of non-token parameter values. The main deliberate difference is that parameters are stored in a Go map keyed by lower-case name (so ordering is not preserved on parse and is instead emitted sorted on format), and errors are returned as Go error values instead of being thrown.

Index

• func Format(m MediaType) (string, error)
• type MediaType
  • func Parse(s string) (MediaType, error)

Examples

• Format
• Parse

Functions

func Format

func Format(m MediaType) (string, error)

Format reconstructs a media type string from a MediaType value. It returns an error if the type or subtype are not valid tokens.

Example

ExampleFormat shows the inverse of Parse: turning a MediaType value back into a canonical string. The type, subtype and suffix are validated as tokens and lower-cased, and any parameters are emitted in a stable sorted order so the result is deterministic. A parameter value that is a plain token is written as-is, while a non-token value would be quoted. Format returns an error only when a component is not a legal token, which is not the case here.

package main

import (
	"fmt"

	"github.com/malcolmston/express/mediatyper"
)

func main() {
	s, err := mediatyper.Format(mediatyper.MediaType{
		Type:       "text",
		Subtype:    "html",
		Parameters: map[string]string{"charset": "utf-8"},
	})
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println(s)
}

Output:
text/html; charset=utf-8

Types

type MediaType

type MediaType struct {
	// Type is the top-level type, e.g. "application".
	Type string
	// Subtype is the subtype without any suffix, e.g. "vnd.api".
	Subtype string
	// Suffix is the optional structured suffix without the "+", e.g. "json".
	Suffix string
	// Parameters holds media type parameters keyed by lower-case name.
	Parameters map[string]string
}

MediaType represents a parsed media type.

func Parse

func Parse(s string) (MediaType, error)

Parse parses a media type string. It validates token syntax for the type, subtype, optional "+suffix" and parameter names, returning an error on invalid input.

Example

ExampleParse shows how a full media type string is broken into its parts. The input here carries a top-level type, a subtype with a structured "+json" suffix, and a charset parameter. Parse lower-cases the type, subtype and suffix, exposes the suffix separately from the base subtype, and unescapes parameter values into a map keyed by lower-case name. The second return value is a non-nil error only when the input is malformed. Printing the individual fields shows exactly how the string was decomposed.

package main

import (
	"fmt"

	"github.com/malcolmston/express/mediatyper"
)

func main() {
	m, err := mediatyper.Parse("application/vnd.api+json; charset=utf-8")
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("type:", m.Type)
	fmt.Println("subtype:", m.Subtype)
	fmt.Println("suffix:", m.Suffix)
	fmt.Println("charset:", m.Parameters["charset"])
}

Output:
type: application
subtype: vnd.api
suffix: json
charset: utf-8