multipart

multipart

import "github.com/kitsunium/sdk/pkg/v1/data/codec/multipart"

Package multipart registers the multipart/form-data codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134):

import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/multipart"

The codec is RFC 7578's multipart/form-data on the standard library's mime/multipart. Its native value is a Form of [Part]s — a file upload is a part with a FileName and a ContentType; any other value travels as one JSON-mediated part. The boundary belongs in the Content-Type header, which a codec has nowhere to return, so ContentType recovers the header value from the body Marshal wrote. Parts, part sizes and the whole body are bounded. It streams.

Everything that dispatches through the registry by format name then reads and writes it: the codec package's Marshal and Unmarshal, config.FSSource and i18n.LoadFS. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships; this package links this one codec, the core package declaring its codes and the standard library, and nothing else. Importing both is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.

Errors

Failures carry the range 0.3.41.*; match them with errs.HasCode, or the sentinels with errors.Is:

CodeMarshalFailed    0.3.41.1  a part could not be written
CodeUnmarshalFailed  0.3.41.2  a malformed part, a part with no name, a missing closing delimiter
CodeValueInvalid     0.3.41.3  an unusable value — no name, or a CR, LF or NUL in a header field
CodeBoundaryInvalid  0.3.41.4  no usable RFC 2046 boundary
CodeLimitExceeded    0.3.41.5  a part, the part count or the body crossed its bound
CodeLimitsInvalid    0.3.41.6  a negative bound

No error message quotes the input.

Index

• Constants
• Variables
• func ContentType(body []byte) (value string, err error)
• type Form
• type Part

Constants

The error codes, range 0.3.41.*, declared in the core (ADR 0160).

const (
    // CodeMarshalFailed is 0.3.41.1: a part could not be written.
    CodeMarshalFailed errs.Code = coremultipart.CodeMultipartMarshalFailed
    // CodeUnmarshalFailed is 0.3.41.2: a malformed part, a part with no name,
    // a missing closing delimiter.
    CodeUnmarshalFailed errs.Code = coremultipart.CodeMultipartUnmarshalFailed
    // CodeValueInvalid is 0.3.41.3: an unusable value — no name, or a CR, LF
    // or NUL in a header field.
    CodeValueInvalid errs.Code = coremultipart.CodeMultipartValueInvalid
    // CodeBoundaryInvalid is 0.3.41.4: no usable RFC 2046 boundary.
    CodeBoundaryInvalid errs.Code = coremultipart.CodeMultipartBoundaryInvalid
    // CodeLimitExceeded is 0.3.41.5: a part, the part count or the body
    // crossed its bound.
    CodeLimitExceeded errs.Code = coremultipart.CodeMultipartLimitExceeded
    // CodeLimitsInvalid is 0.3.41.6: a negative bound.
    CodeLimitsInvalid errs.Code = coremultipart.CodeMultipartLimitsInvalid
)

Format is the name multipart/form-data is registered under. It is an untyped constant, so it goes wherever a format name is taken — the codec package's Marshal, config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.

const Format = "multipart"

Variables

The sentinels, for errors.Is: each carries the code of the same name.

var (
    // MarshalFailed is the sentinel of [CodeMarshalFailed].
    MarshalFailed = coremultipart.MarshalFailed
    // UnmarshalFailed is the sentinel of [CodeUnmarshalFailed].
    UnmarshalFailed = coremultipart.UnmarshalFailed
    // ValueInvalid is the sentinel of [CodeValueInvalid].
    ValueInvalid = coremultipart.ValueInvalid
    // BoundaryInvalid is the sentinel of [CodeBoundaryInvalid].
    BoundaryInvalid = coremultipart.BoundaryInvalid
    // LimitExceeded is the sentinel of [CodeLimitExceeded].
    LimitExceeded = coremultipart.LimitExceeded
    // LimitsInvalid is the sentinel of [CodeLimitsInvalid].
    LimitsInvalid = coremultipart.LimitsInvalid
)

func ContentType

func ContentType(body []byte) (value string, err error)

ContentType returns the Content-Type header value — "multipart/form-data; boundary=…", quoted when the boundary needs it — for a body Marshal wrote, read off its first delimiter line. A body with no recoverable delimiter is refused with CodeBoundaryInvalid.

type Form

Form is the native value of the multipart/form-data Format: a whole body — its RFC 2046 boundary and its parts, in wire order. Marshal one to build an upload; Unmarshal into a *Form to read one. An empty Boundary asks Marshal to generate a delimiter; Unmarshal always fills it with the one it recovered.

type Form = svcmultipart.FormValue

type Part

Part is one section of a Form: a named field, optionally a filename and a media type, and the bytes. Name is required, and a CR, an LF or a NUL in Name, FileName or ContentType is refused, never escaped. Decoding keeps a filename's last path element only.

type Part = svcmultipart.PartValue

Generated by gomarkdoc