body

Reads and parses the request body based on Content-Type. Supports JSON variants (including RFC 7386 merge-patch and RFC 6902 json-patch), application/x-www-form-urlencoded, and multipart/form-data. Includes a fast path for identity-encoded application/json that bypasses the full stream pipeline.

Pipeline stage: Validation

Import

import { body } from "@centralping/ergo";

Options

Option	Type	Default	Description
limit	number	1048576 (1 MiB)	Maximum body size in bytes
decompressedLimit	number	min(10 × limit, 10 MiB)	Maximum decompressed body size (bomb protection)
types	string[]	See below	Allowed Content-Type MIME types
charset	string	'utf-8'	Default character encoding

Default types

• application/vnd.api+json
• application/json
• application/merge-patch+json (RFC 7386)
• application/json-patch+json (RFC 6902)
• application/x-www-form-urlencoded
• multipart/form-data

Return Value

On success, the middleware returns a body descriptor stored at acc.body:

{
  type: "application/json",
  charset: "utf-8",
  encoding: "identity",
  length: 42,
  received: 42,
  raw: '{"name":"Jane"}',
  parsed: { name: "Jane" }
}

Multipart Parsed Shape

For multipart/form-data requests, acc.body includes a boundary field and parsed is an array of part objects — one per form field or file:

{
  type: "multipart/form-data",
  charset: "utf-8",
  encoding: "identity",
  length: 4096,
  received: 4096,
  boundary: "----WebKitFormBoundary7MA4YWxkTrZu0gW",
  raw: "...",
  parsed: [
    { headers: { ... }, name: "avatar", filename: "photo.png", body: Buffer },
    { headers: { ... }, name: "description", filename: undefined, body: Buffer },
  ],
}

Property	Type	Description
headers	object	RFC 7578 §4.8 headers (content-disposition, content-type, content-transfer-encoding) as {type, parameters} entries
name	string	The form field name from Content-Disposition
filename	string | undefined	The original filename (present only for file fields)
body	Buffer	The raw binary content of the part

File fields have a filename property; regular form fields do not. See the File Upload recipe for working examples of filtering files from text inputs in both standalone and ergo-router contexts.

Error Responses

Status	Condition
400 Bad Request	Content-Length mismatch, malformed body, or parse failure
411 Length Required	Neither Content-Length nor chunked encoding present
413 Payload Too Large	Body exceeds limit (or decompressed body exceeds decompressedLimit)
415 Unsupported Media Type	Unrecognized content type or unsupported Content-Encoding

Usage

Standalone

import { compose, body } from "@centralping/ergo";

const pipeline = compose(
  {fn: body({ limit: 2 * 1024 * 1024 }), setPath: "body"},
  // acc.body.parsed === { name: "Jane" }
);

ergo-router

router.post("/users", {
  body: { limit: 2 * 1024 * 1024 },
  validate: {
    body: {
      type: "object",
      properties: { name: { type: "string" } },
      required: ["name"],
    },
  },
  execute: (req, res, acc) => ({
    response: {
      statusCode: 201,
      body: { id: "1", name: acc.body.parsed.name },
    },
  }),
});

RFC References

• RFC 7578 — multipart/form-data
• RFC 7386 — JSON Merge Patch
• RFC 6902 — JSON Patch

Related Recipes

• File Upload — Multipart file uploads with size limits and accessing parsed file content
• PATCH Semantics — RFC 7386 merge-patch and RFC 6902 JSON Patch with content-type enforcement

API Reference

See the auto-generated body API docs.