mpart

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package mpart writes multipart bodies, for replies and webhooks, with mime/multipart.Writer: their model, the checks of the model, and the tables that decode it from mock files. It doesn't parse bodies: net/http parses requests.

Index

Constants

This section is empty.

Variables

View Source
var PartSchema = config.NewSchema(
	partField{
		Key: "name", Kind: config.String, Usage: "Name of the part, in its Content-Disposition: required in form-data.",
		Set: func(d *partDef, v config.Value) error { d.part.Name = v.Str; return nil },
	},
	partField{
		Key: "filename", Kind: config.String, Usage: "File name of the part, in its Content-Disposition.",
		Set: func(d *partDef, v config.Value) error { d.part.Filename = v.Str; return nil },
	},
	partField{
		Key: "content_type", Kind: config.String,
		Usage: "Content-Type of the part. JSON bodies default to application/json, and parts with a filename to application/octet-stream.",
		Set:   func(d *partDef, v config.Value) error { d.part.ContentType = v.Str; return nil },
	},
	partField{
		Key: "header", Kind: config.Any, Usage: "More headers of the part, by name: text or a list of text each.",
		Set: func(d *partDef, v config.Value) error { return headers(v, &d.part.Header) },
	},
	partField{
		Key: "body", Kind: config.Any, Usage: "Body of the part: text as is, anything else as JSON.",
		Set: func(d *partDef, v config.Value) error {
			switch x := v.Any.(type) {
			case nil:
				return config.Invalid(v, v.Key+" is null", `remove it, or write "" for an empty body`)
			case string:
				d.part.Body, d.part.Kind = []byte(x), BodyText
			default:
				b, err := json.Marshal(x, json.Deterministic(true))
				if err != nil {
					return err
				}

				d.part.Body, d.part.Kind = b, BodyJSON
			}

			return nil
		},
	},
	partField{
		Key: "body_base64", Kind: config.String,
		Usage: "Body of the part: bytes in standard base64, for a body that isn't UTF-8 text, such as an image. Line breaks are ignored.",
		Set: func(d *partDef, v config.Value) error {
			b, err := base64.StdEncoding.DecodeString(v.Str)
			if err != nil {
				return config.Invalid(v, v.Key+" isn't standard base64: "+err.Error(), "encode the bytes with base64, padding included")
			}

			d.part.Body, d.part.Kind = b, BodyBytes

			return nil
		},
	},
	partField{
		Key: "body_file", Kind: config.String,
		Usage: "File to read the body from, at each use. Relative paths start at the mock file's directory.",
		Set: func(d *partDef, v config.Value) error {
			if v.Str == "" {
				return errors.New("expected a file name")
			}

			d.part.File = v.Str

			return nil
		},
	},
	partField{
		Key: "delay", Kind: config.Duration,
		Usage: "How long a reply waits before writing the part: milliseconds or a Go duration (1.5s).",
		Set:   func(d *partDef, v config.Value) error { d.part.Delay = v.Dur; return nil },
	},
)

PartSchema decodes a part of a multipart object.

View Source
var SpecSchema = config.NewSchema(
	specField{
		Key: "type", Kind: config.String, Usage: "Subtype of the body, such as form-data, mixed, related or x-mixed-replace.",
		Set: func(s *Spec, v config.Value) error { s.Subtype = v.Str; return nil },
	},
	specField{
		Key: "boundary", Kind: config.String, Usage: "Boundary between the parts. Random when left out.",
		Set: func(s *Spec, v config.Value) error {
			if v.Str == "" {
				return config.Invalid(v, v.Key+" is empty", "leave it out for a random boundary")
			}

			s.Boundary = v.Str

			return nil
		},
	},
	specField{
		Key: "params", Kind: config.Any, Usage: "More parameters of the Content-Type, by name, such as type and start.",
		Set: func(s *Spec, v config.Value) error {
			params := make(map[string]string)
			err := config.Members(v, func(name string, member config.Value) error {
				text, ok := member.Any.(string)
				if !ok {
					return config.Mismatch(member, "a string", config.String)
				}

				params[name] = text

				return nil
			})

			s.Params = params

			return err
		},
	},
	specField{
		Key: "parts", Kind: config.Any, Usage: "Parts of the body, in order.",
		Set: func(s *Spec, v config.Value) error {
			if list, ok := v.Any.([]any); ok && len(list) == 0 {
				return config.Invalid(v, v.Key+" is empty", "add at least one part")
			}

			return config.Items(v, func(item config.Value) error {
				part, err := decodePart(item)
				s.Parts = append(s.Parts, part)

				return err
			})
		},
	},
)

SpecSchema decodes the multipart object of a mock file, as response.multipart and a webhook's multipart parameter write it. PartSchema decodes each of its parts.

Functions

This section is empty.

Types

type BodyKind

type BodyKind int

BodyKind says what the body of a part is.

const (
	BodyBytes BodyKind = iota // bytes, written as they are
	BodyText                  // text, a template when the spec is templated
	BodyJSON                  // JSON, written as it is; it defaults the part's content type to application/json
)

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder writes the body of a Spec. It is safe for concurrent use.

func Compile

func Compile(s *Spec, engine vlatte.TemplateEngine) (*Encoder, error)

Compile checks s, compiles its templates with engine and draws a boundary when s has none. The Encoder copies s: changing s afterwards doesn't change it.

When s is templated, its text is templates: names, filenames, content types, header values, text bodies, and body file names. Byte and JSON bodies, and the content of body files, are written as they are. engine can be nil when s isn't templated.

func (*Encoder) ContentType

func (e *Encoder) ContentType() string

ContentType returns the Content-Type of the body: multipart/<subtype>, with its boundary and parameters.

func (*Encoder) Encode

func (e *Encoder) Encode(data any) ([]byte, []Pause, error)

Encode writes the body, with data for its templates. It returns the body, and where a streamed body waits.

type Header struct {
	Name  string
	Value string
}

Header is a header of a part.

type Issue

type Issue struct {
	Code    string // a config problem code, such as invalid_value
	Path    string
	Message string
	With    string
	Hint    string
}

Issue is a problem of a Spec. Path names where it is, as a mock file names its keys: "boundary" or "parts[1].name". Message follows the path: "parts[1].name is required in a form-data part". A conflict names the other path in With instead.

func (Issue) String

func (i Issue) String() string

String formats the issue as its path and message, then its hint.

func (Issue) Text

func (i Issue) Text(prefix string) string

Text returns the path and message of the issue, with its paths under prefix, such as "response.multipart".

type PartSpec

type PartSpec struct {
	Name        string // the name of a form-data part, in its Content-Disposition
	Filename    string // the filename of its Content-Disposition
	ContentType string
	Header      []Header // more headers, in order
	Body        []byte
	Kind        BodyKind
	File        string        // a file to read the body from, at each Encode
	Delay       time.Duration // how long a streamed reply waits before writing the part
	Err         error         // what went wrong building the part, such as a JSON body that doesn't marshal
}

PartSpec is a part of a multipart body.

type Pause

type Pause struct {
	At    int
	Delay time.Duration
}

Pause is where a streamed body waits: At is the offset of the bytes written after the wait. A part's pause comes right after the delimiter line that opens it, so the part before is whole on the client while it waits.

type Spec

type Spec struct {
	Subtype   string            // such as form-data or mixed: the media type is multipart/<Subtype>
	Boundary  string            // "" draws a random one
	Params    map[string]string // more parameters of the Content-Type, such as type and start for related
	Parts     []*PartSpec
	Templated bool   // the text of the parts is templates: see Compile
	Dir       string // where relative body files open from; "" is the working directory
}

Spec is a multipart body to write.

func Decode

func Decode(v config.Value) (*Spec, error)

Decode decodes the multipart object v of a mock file and checks it. Every problem is keyed under v.Key, as response.multipart.parts[1].name, and each key gets one problem at most. With problems, the spec is what decoded, so a caller can check more of it at once; it is nil when v isn't an object.

func (*Spec) Check

func (s *Spec) Check() []Issue

Check returns the issues of s: what makes it a body that can't be written, or not as asked.

func (*Spec) Doc

func (s *Spec) Doc() map[string]any

Doc returns s as a mock file writes it: the object Decode reads. A byte body is written as text, the same bytes, or in body_base64 when it isn't UTF-8, which JSON and YAML can't hold as text, or when s is templated, where text would read back as a template. The relative body files of its parts are joined to its directory, so they open from the working directory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL