unix-domain-socket

A Node.js project demonstrating HTTP servers over Unix domain sockets and Windows named pipes. This example is designed to test Postman's Unix domain socket URL support.

What are Unix Domain Sockets?

On Unix-like systems (macOS, Linux), a Unix domain socket (UDS) is a special kind of file that lets processes on the same machine communicate using the socket API. Instead of using TCP/IP with localhost and a port number, you use a filesystem path like /tmp/http-socket.sock.

Windows Note: Windows uses Named Pipes (\\.\pipe\myserver) to provide similar functionality.

Postman URL Format

To connect to a Unix domain socket in Postman, use this syntax:

protocol://unix:<socket-path>:<resource-path>

Where:

• protocol (optional): http or https (defaults to http if omitted)
• socket-path: absolute path to the socket file
• resource-path (optional): path to a specific resource (e.g., /hello)

Examples

macOS/Linux:

http://unix:/tmp/http-socket.sock:/hello
unix:/tmp/http-socket.sock:/hello (shorthand)

Windows (Named Pipes):

http://unix:\\\\.\\pipe\\myserver:/hello (backward slash)
http://unix://./pipe/myserver:/hello (forward slash)

Installation

npm install

Usage

Start the Unix Domain Socket Server (macOS/Linux)

npm run server

This starts an HTTP server listening on /tmp/http-socket-<machine-id>.sock (where <machine-id> is a randomly generated hex string) with the following endpoints:

• GET / - Server information and available endpoints
• GET /hello - Simple hello world response
• POST /echo - Echo back the request body
• GET /headers - Returns request headers
• GET /status/201 - Returns 201 status code
• GET /status/404 - Returns 404 status code

Test with the Client

In a separate terminal, run the test client. Make sure to use the same MACHINE_ID that the server displays:

MACHINE_ID=<machine-id-from-server> npm run client

For example, if the server shows Machine ID: a1b2c3d4e5f6g7h8, run:

MACHINE_ID=a1b2c3d4e5f6g7h8 npm run client

This will make test requests to all available endpoints.

Tip: You can also set a custom machine ID when starting the server:

MACHINE_ID=my-custom-id npm run server

Test with Postman

With the server running, copy the socket path from the server output (which includes the machine ID) and use it in Postman. For example, if the server shows /tmp/http-socket-a1b2c3d4e5f6g7h8.sock, use these URLs:

unix:/tmp/http-socket-a1b2c3d4e5f6g7h8.sock:/
unix:/tmp/http-socket-a1b2c3d4e5f6g7h8.sock:/hello
unix:/tmp/http-socket-a1b2c3d4e5f6g7h8.sock:/headers
unix:/tmp/http-socket-a1b2c3d4e5f6g7h8.sock:/echo (POST request)

The server output will display the exact Postman URLs to use.

Windows Named Pipes

For Windows systems, use the named pipe server:

npm run server:windows

Then test in Postman with:

http://unix://./pipe/myserver:/hello

Available Scripts

• npm run server - Start Unix domain socket server (macOS/Linux)
• npm run client - Run test client
• npm run server:windows - Start named pipe server (Windows only)
• npm start - Run the default index.js
• npm run dev - Run in watch mode

Requirements

• Node.js >= 18.0.0

Files

• server.js - HTTP server using Unix domain socket (macOS/Linux)
• client.js - Test client for making requests
• server-windows.js - HTTP server using Windows Named Pipes
• index.js - Main entry point (starter template)

License

MIT