@inteli.city/node-red-contrib-http+

Enhanced HTTP nodes for Node-RED with built-in authentication, request validation, and caching.

What is this?

@inteli.city/node-red-contrib-http+ provides enhanced versions of Node-RED's HTTP nodes with built-in authentication, validation, and improved request handling.

These nodes are designed to be compatible with the standard Node-RED HTTP flow while adding capabilities commonly implemented manually in flows.

Key differences from standard HTTP nodes

| Feature | Standard nodes | http+ nodes | |---------|----------------|-------------| | Authentication | Not built-in | Built-in (Basic + Cognito) | | Request validation | Manual (function nodes) | Built-in (Zod) | | File upload handling | Basic | Structured (msg.files) | | Data normalization | Manual | Built-in via Zod transforms | | Streaming responses | Limited/manual | First-class support | | Backend caching | Not available | Built-in (http.in+) | | Browser cache control | Manual headers | Built-in (http.out+) |

Compatibility

• http.in+ and http.out+ follow the same flow model as the standard nodes
• http.request+ is a drop-in replacement for the standard http request node
• Existing flows can be migrated incrementally

Standard:  http in ──→ function ──→ http response
With http+: http.in+ ──→ (validated + authenticated) ──→ http.out+

When to use http+ nodes

Use http+ when you need:

• Authentication at the HTTP boundary
• Input validation without extra function nodes
• Cleaner and more predictable request handling

Use standard nodes when:

• You need minimal setup
• You are prototyping quickly without constraints

Index

• Nodes
• Install
• Core Concepts
• Caching
• Authentication
• Validation with Zod
• Swagger / OpenAPI
• File uploads
• http.request+
• http.out+
• Best practices

Nodes

| Node | Role | |------|------| | http.in+ | Receives HTTP requests. Runs auth, Zod validation, and optional backend caching before sending msg downstream. | | http.request+ | Makes outgoing HTTP requests with Nunjucks-templated headers and body, request queuing, and optional auth. | | http.out+ | Sends the HTTP response back to the caller. Optionally controls browser caching via Cache-Control. | | http.auth.out+ | Config node — manages outgoing authentication (Basic Auth, JWT from endpoint) for http.request+. |

Install

cd ~/.node-red
npm install @inteli.city/node-red-contrib-http+

Core Concepts

Message properties

| Property | Contains | |----------|----------| | msg.payload | Request body (POST/PUT/PATCH) or query object (GET) | | msg.req.query | Query string as object — GET /search?term=abc → { term: "abc" } | | msg.req.params | Route parameters — GET /users/42 → { id: "42" } | | msg.req.headers | Request headers | | msg.validated | Parsed + validated object from Zod (only when validation passes) | | msg.user | Mapped user identity. For Basic Auth: the username string. For Cognito: fields mapped from the JWT payload (only when "Expose user to flow" is enabled). | | msg.res | Response handle — passed to http.out+ to send the reply |

Basic flow

http.in+ ──→ [your logic] ──→ http.out+

inject ──→ http.request+ ──→ debug

Caching

http+ supports two distinct caching mechanisms that operate at different layers and solve different problems.

| Feature | Backend cache (http.in+) | Browser cache (http.out+) | |---------|----------------------------|-----------------------------| | Layer | Server | Client (browser) | | When applied | Before flow execution | After response is sent | | Effect | Skips the flow entirely on a hit | Browser may reuse the response | | Default | Disabled | Disabled | | Risk | Serving stale or incorrect data | Stale data in the browser |

They can be used independently or combined.

How they work

Backend cache runs at the entry point of the flow. If a valid cached response exists for the incoming request, it is returned immediately — no downstream node runs.

Browser cache runs at the response level. It tells the client how long to keep the response locally. The flow still runs on every server request; the browser decides whether to send the request at all.

Backend cache (http.in+)

In the node editor, backend cache is labelled "Server cache" to distinguish it from browser cache.

Caches full HTTP responses on the server. Repeated identical GET requests are served from cache without executing any downstream nodes.

Active only for GET requests. The Cache field controls the scope:

| Mode | Who shares the cache | Auth required | |------|----------------------|---------------| | Disabled | — | — | | Public | All requests with the same URL + query | No | | Per-user | Each authenticated user has their own entry | Yes | | By claim | Users sharing the same value for a chosen identity field | Yes |

Cache key — derived from URL path + sorted query parameters + identity (for per-user and by-claim modes). Headers, cookies, and request body are not part of the key.

Storage — responses are stored on disk:

<userDir>/.runtime_data/cache/http+/

The directory is created automatically if it does not exist.

TTL — controlled by the "Cache duration (s)" field. Expired entries are ignored and replaced on the next request.

Observability — every cached response includes:

X-Cache: HIT         →  served from cache; flow was skipped
X-Cache: MISS        →  cache was empty or expired; flow ran
X-Cache-Scope: public | user | claim:<field>

Examples:

GET /products          → Public cache (shared across all callers)
GET /profile           → Per-user cache (isolated per authenticated user)
GET /dashboard         → By claim: tenantId (shared per tenant, isolated between tenants)

Browser cache (http.out+)

Instructs the browser to store the response locally and reuse it for subsequent requests. The server still handles every request that reaches it — the browser controls whether a request is sent at all.

What it does:

When enabled, http.out+ adds the following header to every response:

Cache-Control: public, max-age=<duration>

Override rule: if msg.headers['cache-control'] is set anywhere in the flow, it takes precedence over the node setting. This allows per-request control without changing node configuration.

Example:

[http.in+  GET /logo.png] ──→ [read file] ──→ [http.out+  browser cache: 86400 s]

The browser caches the image for 24 hours. On subsequent page loads, no network request is made.

⚠️ When NOT to use browser cache

• Dynamic responses that change between requests
• User-specific or session-specific data
• Any endpoint where a stale cached response would cause incorrect behavior

Using both together

Backend cache and browser cache can be combined on the same endpoint:

[http.in+  GET /summary  cache: 60 s] ──→ [compute] ──→ [http.out+  browser cache: 60 s]

• The server caches the response for 60 seconds — the flow is skipped on repeated hits.
• The browser also caches it for 60 seconds — the request may not leave the client at all.

Align both TTLs to avoid a situation where the browser caches a response longer than the server would serve the same stale version.

For highly dynamic data, leave both disabled.

Authentication

Configure authentication by creating an http.auth.config+ config node and attaching it to http.in+.

| Type | Behaviour | |------|-----------| | None | All requests pass through | | Basic Auth | Validates Authorization: Basic … header. Browser login popup triggered automatically via WWW-Authenticate. Supports single-user and multi-user modes (see below). | | Cognito JWT | Validates a Bearer token against a JWKS endpoint. Token accepted from Authorization: Bearer <token> or ?token=. JWKS keys are cached for 1 hour. |

Failed authentication returns 401 and stops the flow.

Basic Auth modes

Single-user (default): Enter a username and password directly in the config node. Credentials are stored securely via Node-RED's credentials system (not in the exported flow).

Multiple users (JSON): Enable the "Use multiple users" option and provide a JSON object mapping usernames to passwords:

{
  "admin": "password123",
  "user": "abc123"
}

Warning: Passwords in JSON mode are stored in plain text in the flow configuration. Use only in trusted environments.

JWKS caching

Cognito public keys (JWKS) are cached in memory to reduce latency and avoid repeated requests to AWS.

• Cache duration: 1 hour
• Keys are cached per kid (key ID)
• A new key is fetched automatically if an unknown kid is received

This improves performance while still supporting key rotation. If AWS rotates signing keys, new keys will be picked up automatically after cache expiration or when a new kid appears.

Cognito user mapping

After successful JWT validation, the Authorization header and ?token= query parameter are always removed from the request before it enters the flow.

To expose user identity in msg.user, enable "Expose user to flow" in the config node and provide a JSON mapping:

{
  "id": "sub",
  "email": "email",
  "roles": "cognito:groups"
}

Keys are the output field names in msg.user; values are the JWT claim names to read from. Fields missing from the token are set to undefined.

If "Expose user to flow" is disabled, msg.user is not set — no JWT data propagates into the flow.

Request sanitization

After successful authentication, credentials are removed from the request before dispatch:

| Auth type | Removed | |-----------|---------| | Basic Auth | msg.req.headers.authorization | | Cognito JWT | msg.req.headers.authorization, msg.req.query.token |

This prevents tokens and passwords from leaking into downstream nodes.

Validation with Zod

http.in+ can validate every incoming request before passing it downstream.

Enabling validation

1. Open the http.in+ node editor.
2. Check Enable Zod validation.
3. Enter a Zod schema expression in the Schema textarea.

The schema receives a single object:

{
  body:   // request body (msg.payload)
  query:  // query string parameters (msg.req.query)
  params: // route parameters (msg.req.params)
  files:  // uploaded file metadata (when file upload is enabled)
}

Use the appropriate field depending on the HTTP method:

| Method | Use | |--------|-----| | GET, DELETE | query, params only — no body | | POST, PUT, PATCH | body, query, params |

Defining body in a GET or DELETE schema is ignored at runtime. A warning is logged at deploy time.

Full usage guidance (method table, type coercion, Swagger behavior) is available inline in the node editor UI.

If validation passes, msg.validated contains the parsed result and the flow continues normally.

If validation fails, the node returns HTTP 400 immediately — no downstream node is executed:

{
  "error": "invalid_request",
  "details": [
    { "code": "invalid_type", "path": ["body", "age"], "message": "Expected number, received string" }
  ]
}

Important: query and param values are always strings

HTTP query strings and route params arrive as strings. Use z.coerce to convert them:

z.coerce.number()   // "42" → 42
z.coerce.boolean()  // "true" → true

Transforms and normalization

Zod can transform values as part of validation — trimming whitespace, converting case, coercing types, etc. The transformed result is what ends up in msg.validated. msg.payload always remains the original, unmodified request body.

z.object({
  query: z.object({
    term: z.string().trim().toLowerCase(),
    page: z.coerce.number().int().min(1)
  })
})

The flow receives msg.validated.query.term already trimmed and lowercased — no manual cleanup needed.

File validation

Zod validates file metadata (mime type, size, etc.), not file content. Files from the upload are available in msg.files as an array — validate the first entry or a named field:

z.object({
  files: z.object({
    avatar: z.object({
      mimetype: z.enum(["image/png", "image/jpeg"]),
      size: z.number().max(2_000_000)
    })
  })
})

Examples

Example 1 — Body validation (POST)

Route: POST /users

Schema:

z.object({
  body: z.object({
    name: z.string().min(1),
    age:  z.number().int().min(0)
  })
})

Valid request body:

{ "name": "Alice", "age": 30 }

Invalid — returns 400:

{ "name": "", "age": -1 }

Example 2 — Query validation (GET)

Route: GET /search?term=node-red&page=2

Schema:

z.object({
  query: z.object({
    term: z.string().min(1),
    page: z.coerce.number().int().min(1).optional()
  })
})

page arrives as a string from the URL — z.coerce.number() converts it automatically.

Example 3 — Route parameter validation

Route: GET /users/:id

Schema:

z.object({
  params: z.object({
    id: z.string().uuid()
  })
})

Rejects any request where :id is not a valid UUID before your logic runs.

Example 4 — Combined: params + query + body

Route: PATCH /users/:id?notify=true

Schema:

z.object({
  params: z.object({
    id: z.string().uuid()
  }),
  query: z.object({
    notify: z.coerce.boolean().optional()
  }).optional(),
  body: z.object({
    email: z.string().email().optional(),
    role:  z.enum(["admin", "user", "viewer"]).optional()
  })
})

msg.validated will contain the fully parsed and typed object for use downstream.

Validation error format

{
  "error": "invalid_request",
  "details": [
    {
      "code":    "invalid_type",
      "path":    ["body", "age"],
      "message": "Expected number, received string"
    },
    {
      "code":    "too_small",
      "path":    ["body", "name"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

details is the raw Zod ZodError.errors array. Each entry contains a path array indicating exactly which field failed.

Best practices

| Scenario | Recommendation | |----------|----------------| | Required identifiers | Use route params (:id) with z.string().uuid() or similar | | Filters and options | Use query string with z.coerce for number/boolean | | Structured input data | Use request body (body) — POST/PUT/PATCH only | | GET / DELETE filtering | Use query — never body | | All query/param values | Always use z.coerce.* — they arrive as strings | | Optional sections | Wrap entire query or params in .optional() if the route doesn't always have them | | Schema errors at deploy | The node logs the error and disables validation — it does not crash | | Swagger visibility | Only nodes with a valid Zod schema appear in /docs |

Swagger / OpenAPI

http.in+ nodes with a valid Zod schema are automatically registered in an OpenAPI 3.0 spec. No extra configuration is required.

| Endpoint | Returns | |----------|---------| | GET /docs/openapi.json | Raw OpenAPI spec (JSON) | | GET /docs | Redirects to /docs/ | | GET /docs/ | Swagger UI |

Only endpoints where Zod validation is enabled and the schema compiled successfully appear in the spec. The spec updates automatically on each deploy — no stale entries.

What gets documented

| Zod key | OpenAPI output | |---------|----------------| | body | requestBody → reusable schema in components.schemas | | files (uploads enabled) | requestBody multipart → reusable schema in components.schemas | | query | parameters (in: query) — inline, not a reusable schema | | params | parameters (in: path) — inline, not a reusable schema |

body and files schemas are promoted to components.schemas so Swagger UI displays them under the Schemas section and operations link back to them via $ref. Query and path parameters stay as inline parameter objects — converting them into shared schemas would distort their HTTP semantics without any benefit.

Schema naming

Schema names are derived from the HTTP method and path — they are stable and deterministic across restarts and redeploys:

POST  /users              → PostUsersBody
POST  /users/{id}/avatar  → PostUsersIdAvatarForm   (file upload)
PUT   /products/:name     → PutProductsNameBody
PATCH /                   → PatchRootBody

Type representation

Schemas always reflect post-validation (semantic) types, not the raw HTTP transport type:

z.coerce.number()   → { type: "number" }   (not "string")
z.coerce.boolean()  → { type: "boolean" }  (not "string")

Full example

Route: POST /users

Zod schema:

z.object({
  body: z.object({
    name:  z.string(),
    email: z.string(),
    age:   z.coerce.number().optional()
  }),
  query: z.object({
    dry_run: z.coerce.boolean().optional()
  }),
  params: z.object({})
})

Generated /docs/openapi.json (simplified):

{
  "paths": {
    "/users": {
      "post": {
        "parameters": [
          {
            "name": "dry_run",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PostUsersBody" }
            }
          }
        },
        "responses": { "200": { "description": "OK" } }
      }
    }
  },
  "components": {
    "schemas": {
      "PostUsersBody": {
        "type": "object",
        "properties": {
          "name":  { "type": "string" },
          "email": { "type": "string" },
          "age":   { "type": "number" }
        },
        "required": ["name", "email"]
      }
    }
  }
}

age is absent from required because it is .optional(). dry_run is a query parameter, not a schema entry. Swagger UI renders PostUsersBody in the Schemas section and links to it from the operation.

File upload example

Route: POST /documents (file uploads enabled)

Zod schema:

z.object({
  files: z.object({
    document: z.any(),
    thumbnail: z.any().optional()
  }),
  body: z.object({
    title: z.string()
  })
})

Generated schema (PostDocumentsForm):

{
  "type": "object",
  "properties": {
    "document":  { "type": "string", "format": "binary" },
    "thumbnail": { "type": "string", "format": "binary" },
    "title":     { "type": "string" }
  },
  "required": ["document", "title"]
}

File and body fields are merged into a single multipart/form-data schema. File fields are always represented as { type: "string", format: "binary" }.

What does NOT appear in the spec

• Endpoints with Zod disabled
• Endpoints where the schema failed to compile
• Response schemas (out of scope — http.out+ does not guarantee response shape)
• Query and path parameter schemas (they remain as parameters)

File uploads

http.in+ supports multipart (multipart/form-data) file uploads on POST routes. The upload option is not available for GET, PUT, PATCH, or DELETE.

If file upload is enabled, uploaded files are available in msg.files — they are not included in msg.payload.

Enabling uploads

1. Open the http.in+ node editor.
2. Check Enable file uploads.
3. Choose Storage: Memory (buffer) or Disk (temp files).
4. Set Max size (MB) (default: 5 MB).
5. For disk storage, optionally set a Temp dir (defaults to the OS temp directory).

msg.files

When files are uploaded, msg.files is an array of objects:

| Property | Present | Contains | |----------|---------|----------| | fieldname | always | Form field name used for the upload | | originalname | always | Original filename from the client | | mimetype | always | MIME type (e.g. image/png) | | size | always | File size in bytes | | storage | always | "memory" or "disk" | | buffer | memory only | Buffer containing the file data | | path | disk only | Absolute path to the saved file |

Size limit

If a file exceeds the configured limit, the node returns 413 immediately:

{ "error": "file_too_large" }

Disk storage — cleanup

When using disk storage, files are written to the temp directory and not deleted automatically. Your flow is responsible for removing them after use (e.g. via a function node calling fs.unlink).

http.request+

Makes outgoing HTTP requests with Nunjucks-templated headers and body, configurable concurrency, and optional outgoing authentication via http.auth.out+.

Inputs

| Property | Type | Description | |----------|------|-------------| | msg.url | string | Target URL — overrides the node URL when set. Supports Mustache syntax | | msg.method | string | HTTP method when the node is configured to use msg.method | | msg.stop | boolean | Set to true to cancel all running and queued requests |

Outputs

| Property | Type | Description | |----------|------|-------------| | msg.payload | string | object | buffer | Response body (format controlled by Return) | | msg.statusCode | number | HTTP response status code | | msg.headers | object | Response headers | | msg.responseUrl | string | Final URL after any redirects |

Templates

Body and Headers are Nunjucks templates rendered against the full msg object at runtime. Objects coerce to JSON automatically when interpolated — no | dump filter needed.

{{ payload }}               → msg.payload, JSON if it is an object
{{ payload.id }}            → nested scalar, raw value
{{ topic }}                 → msg.topic

Body

Sent for POST, PUT, and PATCH only. If the rendered output is valid JSON it is sent with Content-Type: application/json; otherwise as a plain string. Leave empty to send no body.

{{ payload }}
{"id": {{ payload.id }}, "event": "{{ topic }}"}

Headers

Must render to a JSON object. Use {} to send no custom headers.

Static authentication (Bearer tokens, API keys) belongs here:

{"Authorization": "Bearer {{ payload.token }}"}
{"X-API-Key": "abc123"}

Authentication

Attach an http.auth.out+ config node via the Auth field for authentication requiring lifecycle management (credential storage, automatic token refresh). For static tokens or keys with no lifecycle needs, define them in the Headers template directly.

Header merge order: auth-generated headers are applied first; Headers template values are applied after and take precedence. A user-defined Authorization header in the Headers template silently overrides the auth-generated one.

Concurrency and queue

The Queue setting (default: 1) controls how many requests run in parallel. Incoming messages beyond that limit are held in a FIFO queue.

To abort all pending and in-flight requests:

• Send msg.stop = true
• Click the kill button (⏹) in the node editor

http.auth.out+

Config node that manages outgoing authentication for http.request+. Attach it via the Auth field in the request node editor.

Authentication types

None

No authentication. No headers added.

Basic Auth

Stores username and password using Node-RED's secure credentials system. Adds on every request:

Authorization: Basic <base64(username:password)>

Credentials are never included in exported flow definitions.

JWT (from endpoint)

Fetches an access token from a token URL, caches it, and adds:

Authorization: Bearer <token>

| Field | Description | |-------|-------------| | Token URL | URL of the token endpoint | | Method | HTTP method for the token request (POST, GET, PUT) | | Username / Password | Stored securely via Node-RED credentials. Available in Body and Headers templates as credentials.username and credentials.password | | Body | Nunjucks template for the token request body (POST / PUT only). Context: msg + credentials.* | | Headers | Nunjucks template for token request headers. Must render to a JSON object | | Token field | Key to read from the token endpoint response (default: access_token) | | Fallback TTL | Cache duration in seconds when expires_in is absent or exceeds this value (default: 1200) |

Body template example:

{"username": "{{ credentials.username }}", "password": "{{ credentials.password }}"}

The credentials namespace is only available within JWT token request templates — it is not injected into the main request.

Token caching

Tokens are cached in memory per config node instance. Effective TTL is min(expires_in, fallback TTL) with a 30-second safety margin. Concurrent fetches are deduplicated — if multiple requests arrive while a fetch is in progress they all wait for the same result. Cache is reset on redeploy.

401 auto-refresh

On a 401 from the target API, the cache is invalidated and a new token is fetched. The request is retried once with the fresh token. If the retry also returns 401, or the token fetch fails, a warning is emitted via node.warn and the response is passed through unchanged.

http.out+

Sends the HTTP response back to the original caller. Must be connected to the same flow started by http.in+.

Controlling the response via msg:

| Property | Effect | |----------|--------| | msg.payload | Response body | | msg.statusCode | HTTP status code (default: 200) | | msg.headers | Extra response headers | | msg.cookies | Cookies to set or clear |

If msg.payload is an object, the response is sent as JSON automatically.

Browser caching

http.out+ can automatically set browser cache headers without requiring a function node.

Enable Enable browser cache in the node editor and set Cache duration (s). The node will add:

Cache-Control: public, max-age=<duration>

This does not affect server-side execution — the flow always runs when a request reaches the server. The browser uses the header to decide whether to skip the request entirely on subsequent calls.

If msg.headers['cache-control'] is set anywhere in the flow, it overrides the node setting. This allows per-request cache control without changing node configuration.

Use for static or infrequently-changing responses (images, scripts, reference data). Avoid for user-specific or time-sensitive responses.

For a full explanation including TTL guidance, safety rules, and combining with backend cache, see the Caching section.

Streaming responses

You can stream a response instead of sending a buffer. Useful for large files or when proxying a stream from another source.

Set msg.stream to any readable Node.js stream:

msg.stream = fs.createReadStream("/tmp/file.zip");

If msg.stream is set, the stream is piped directly to the response. If it is not set, msg.payload is sent normally.

msg.headers and msg.statusCode behave the same in both modes.

File structure

httpproxy+.js/.html         — http.proxy+ config node (proxy for http.request+); includes proxy resolution utility
httpin+.js/.html            — http.in+ and http.out+ nodes
httprequest+.js/.html       — http.request+ node
http-auth-config+.js/.html  — http.auth.config+ config node
libs/swagger.js             — OpenAPI spec generation and /docs/ + /docs/openapi.json route registration