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 ¶
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.
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 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 ¶
ContentType returns the Content-Type of the body: multipart/<subtype>, with its boundary and parameters.
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.
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 ¶
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 ¶
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 ¶
Check returns the issues of s: what makes it a body that can't be written, or not as asked.
func (*Spec) Doc ¶
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.