Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Building and Consuming Services

Building a SOAP Server in Node.js

Build a working SOAP 1.1 server from scratch in Node.js - parse envelopes, dispatch operations, return responses and faults, and harden the endpoint against oversized and unsafe XML.

Most developers use a toolkit to build SOAP services: Apache CXF or JAX-WS in Java, WCF or CoreWCF in C#, zeep and spyne in Python, soap in npm. Toolkits generate WSDL files, validate messages and hide the XML. They are the right choice for production work. But if you have never seen what happens underneath, errors in their output will feel like magic.

So in this lesson you will build the core of a SOAP 1.1 server yourself, with nothing but node:http. You will see the three jobs every SOAP server performs: parse the envelope, dispatch to an operation, and serialize a response or a fault.

Our runner has no npm packages and no outside network, so the server listens on 127.0.0.1 and the program calls itself with fetch. The small XML reader below is a teaching tool: it handles elements, attributes, text and namespaces prefixes, but it is not a full XML parser. In production, use a maintained library.

The three jobs of a SOAP server

flowchart LR
  A["HTTP POST"] --> B["Parse Envelope"]
  B --> C["Find operation in Body"]
  C --> D["Call handler"]
  D --> E["Response envelope"]
  D --> F["Fault envelope"]
  E --> G["HTTP 200"]
  F --> H["HTTP 500"]

A request becomes a handler call; the outcome becomes either a response or a fault.

The operation name is the first element inside Body. The handler gets the child elements as arguments and returns an object, which we turn back into XML.

A tiny XML reader

We need to turn XML text into a tree. This 20-line reader tokenizes tags and text, strips namespace prefixes from names, and decodes the five predefined entities.

Node.js A minimal XML reader

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The DOCTYPE check matters: documents with custom entities can trigger "billion laughs" expansion or external file reads (XXE) in poorly configured parsers. A SOAP message never needs a DTD, so refusing it outright is the safest policy.

The dispatcher

Now the server itself. Operations are registered as plain functions. The server reads the body, finds the operation, calls it, and serializes. Anything that throws a SoapFault becomes a fault; any other error becomes a generic Server fault so internals never leak.

Node.js A complete SOAP calculator service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Study the output. The Crash operation logs the secret on the server (the [server log] line) but the caller only sees "Internal error". Divide by zero is the caller's fault, so it is a Client fault; the same code on a real server would use a Server fault for something like a database outage.

What a production server adds

Our server is about 40 lines of logic. A production framework adds much more:

  • WSDL generation and serving. The ?wsdl URL returns the contract so clients can generate stubs (see Dynamic Clients from a WSDL).
  • Schema validation. Requests are checked against the XSD types before the handler runs, so <a>abc</a> is rejected with a clear fault.
  • SOAPAction routing. The HTTP header can select the operation without parsing the body.
  • SOAP 1.2 support. Different namespace, content type (application/soap+xml) and fault structure.
  • Headers. Security, addressing and custom headers processed before the body.
  • Attachments. MTOM/XOP for binary data.

Limit the request size, reject DTDs, set time-outs, and never expose stack traces. SOAP endpoints are frequent targets because XML parsers have a long history of vulnerabilities.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a SOAP server find the operation name?

    In document/literal and RPC styles alike, the Body's first child identifies the operation (or, for wrapped style, the operation wrapper).
  2. 2. Why should a SOAP server refuse messages that contain a DOCTYPE?

    DTDs enable entity expansion and XXE. A SOAP message never needs one.
  3. 3. An unexpected exception happens inside a handler. What should the caller see?

    Internal details help attackers. Return a generic fault and log the specifics.
  4. 4. Which HTTP status does our SOAP 1.1 server use for a fault?

    SOAP 1.1 over HTTP specifies 500 for fault responses.

Summary

  • A SOAP server parses the envelope, dispatches on the first Body child, and serializes a response or fault.
  • Return Client faults for caller mistakes and generic Server faults for internal errors.
  • Reject DTDs, cap message size and escape every value placed in XML.
  • Toolkits add WSDL, schema validation, SOAPAction routing, headers, SOAP 1.2 and attachments.

Next: Building a SOAP Client in Node.js