# HttpServer

> Documentation for Redweb 0.16.5. Install that exact version when following these examples.

Lower-level Express HTTP listener with parsers, CORS, static assets and services. Prefer defineApp for new applications; use HttpServer when you explicitly need its immediately listening constructor or custom listener ownership.

## Explain it like I’m five

Think of HttpServer as a furnished storefront: Express is the building, while Redweb installs the front door, service counter, signs, and sensible safety rails before you open.

## When should I use it?

Choose it when Redweb should own a normal HTTP listener and you still want direct access to Express for middleware or one-off routes.

## Follow the example

This API pattern illustrates the named surface; it may require application-owned classes, credentials, or assets. Start from a complete recipe for a runnable application.

```js
import { HttpServer, METHODS } from 'redweb'

const server = new HttpServer({
  port: 4000,
  bind: '0.0.0.0',
  publicPaths: ['./static'],
  services: [
    { serviceName: '/ping', method: METHODS.GET, function: (req, res) => res.json({ pong: true }) },
  ],
})

// Express is still available:
server.app.get('/health', (req, res) => res.send('ok'))
```

1. Redweb creates the Express application and installs the configured parsers, CORS policy, static folders, and services.
2. The server binds to the requested interface unless listen is false.
3. The app property remains the same Express application, so adding /health does not require a Redweb abstraction.

## Options

- port: number (default 80)
- bind: string (default 0.0.0.0)
- publicPaths: string[] (default ["./public"])
- services: array of { serviceName, method, function }
- listen: boolean (default true); set false to build app without binding a port
- listenCallback: function invoked after listen
- encoding: "json" | "urlencoded" (default json)
- corsOptions: passed to cors when explicitly configured (default false, including undefined/null; no wildcard CORS). CORS read access does not permit cross-origin unsafe methods.
- publicOrigin: exact external HTTP(S) origin when a trusted TLS proxy forwards to a private listener; allows same-origin browser mutations from that public origin without trusting arbitrary forwarded headers

## Methods and members

### constructor(options)

Merges defaults, wires body parsing and opt-in CORS, contains static serving inside each public root, registers REST services, and starts listening unless listen is false. Unsafe requests with a foreign Origin or Sec-Fetch-Site other than same-origin/none are rejected; cookie-bearing unsafe requests also require a same-origin signal.

### app (Express instance)

Use the returned `app` to add middleware or routes exactly like a normal Express server.

## What should I watch for?

Use listen: false when another object must own the Node listener; two owners trying to bind the same port is an application design error.