HTTP Server & Native Transcoding

Automatic XML ↔ JSON Conversion

High-performance, bi-directional streaming transcoder built directly into the native XHSC networking stack—automatically converting incoming XML payloads to JSON (xml2json) and mirroring JSON responses back to XML (json2xml).

Go-Native Transcoding

XML parsing and serialization run inside the XHSC Go core before the payload reaches Node.js or Bun, keeping the JS event loop unblocked.

Bi-Directional Mirroring (autoReply)

Write standard JSON handlers in TypeScript. If the client sent XML, XHSC automatically transcodes your JSON response back to application/xml.

Virtual Body Proxy

ConversionProxyMiddleware wraps req.body so XML attributes (e.g. @id) and #text nodes are accessed naturally as standard properties.

Content Sniffing

Detects XML payloads starting with < even when clients omit Content-Type or send generic text/plain headers.

Server Configuration

Enable native conversion in createServer via the conversion option:

typescript
import { createServer } from "xypriss";

const app = createServer({
    server: { port: 3000 },
    conversion: {
        enabled: true,
        xmlToJson: true,          // Convert incoming XML -> JSON (req.body)
        autoReply: true,          // Convert outgoing JSON -> XML for XML callers
        attributePrefix: "@",     // Prefix for XML attributes in JSON
        textContentKey: "#text",  // Key for mixed text + attribute nodes
        maxConversionSize: "10mb",
        strictParsing: true,      // Return 400 Bad Request on malformed XML
        contentSniffing: true,    // Auto-detect '<' payloads without XML header
    },
});

app.post("/api/orders", (req, res) => {
    // Even if the client sent application/xml, req.body is already JSON!
    const { order } = req.body;

    // Reply with standard JSON; XHSC converts it to XML if autoReply is true
    res.json({
        status: "accepted",
        orderId: order.id,
    });
});

app.start();

How Bi-Directional Transcoding Works

1. Incoming Request (xml2json)

When a non-GET request arrives with Content-Type: application/xml or text/xml (or starts with < when contentSniffing is enabled):

  • XHSC parses the XML body natively and converts it into JSON.
  • Sets X-XHSC-Origin-Format: xml and X-XHSC-Origin-Content-Type headers so downstream middleware knows the original format.
  • Replaces the request Content-Type with application/json so your route handler receives a parsed req.body object.

2. Outgoing Response (json2xml)

When autoReply: true is enabled:

  • XHSC checks if X-XHSC-Origin-Format is xml and the handler response Content-Type is application/json.
  • Unless the client explicitly sent Accept: application/json, XHSC transcodes the JSON response body into XML and sets Content-Type: application/xml.
Accept Header Negotiation
If an XML client explicitly sets Accept: application/json, XHSC respects the client's preference and skips json2xml response transcoding, returning JSON directly.

Virtual Body Proxy (Attributes & Text Unwrapping)

When XHSC converts XML attributes and text nodes to JSON using attributePrefix (default "@") and textContentKey (default "#text"), XyPriss's ConversionProxyMiddleware wraps req.body in a recursive Proxy so you can access properties cleanly without bracket notation:

Incoming XML Payload
<order id="ORD-9042" currency="USD">
  <customer>Jane Doe</customer>
  <total>149.99</total>
</order>
TypeScript Handler Access
app.post("/api/orders", (req, res) => {
    const { order } = req.body;

    // Attribute '@id' is accessible directly as 'order.id'
    console.log(order.id);       // "ORD-9042"
    console.log(order["@id"]);   // "ORD-9042" (also works)
    console.log(order.currency); // "USD"

    // Text-only nodes unwrap automatically
    console.log(order.customer); // "Jane Doe"
    console.log(order.total);    // "149.99"

    res.json({ received: order.id });
});

Configuration Options Reference

OptionTypeDefaultDescription
enabledbooleanfalseEnables the native XHSC data conversion pipeline.
xmlToJsonbooleanfalseAutomatically converts incoming XML payloads to JSON on req.body.
autoReplybooleanfalseAutomatically converts outgoing JSON responses back to XML when the request originated as XML.
attributePrefixstring"@"Prefix used for XML attributes when converted to JSON keys.
textContentKeystring"#text"Key name for XML text content when a node contains both attributes and text.
maxConversionSizenumber | string—Maximum payload size allowed for conversion (bytes or string, e.g. "10mb").
strictParsingbooleanfalseIf true, malformed XML returns 400 Bad Request. If false, the original body is forwarded with X-XHSC-Conversion-Error.
contentSniffingbooleanfalsePeeks the first byte of missing or generic Content-Type payloads; if it starts with <, treats it as application/xml.
XJSON API

Explore XyPriss's high-performance BigInt-safe, streaming JSON serializer.