NNG_HTTP_HANDLER_ALLOC(3http)

💅 NNG_HTTP_HANDLER_ALLOC (3http) — the NNG Reference Manual, bestie edition

okay so real talk, this is the NNG Reference Manual page for the whole nng_http_handler_alloc family, and it's lowkey the moment your HTTP server gets ✨personality✨.

🌸 NAME

nng_http_handler_alloc — allocate an HTTP server handler 🎀

✨ SYNOPSIS

#include <nng/nng.h>
#include <nng/supplemental/http/http.h>

typedef struct nng_http_handler nng_http_handler;

int nng_http_handler_alloc(nng_http_handler **hp, const char *path,
    void (*func)(nng_aio *);

int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path,
    const char *dirname);

int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path,
    const char *filename);

int nng_http_handler_alloc_redirect(nng_http_handler **hp, const char *path,
    uint16_t status, const char *location);

int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
    const void *data, size_t size, const char *content_type);

(yes bestie, that first prototype is missing a closing paren in the original — not me, I'm just the messenger 🫶 copy it exact.)

🦋 DESCRIPTION

The nng_http_handler_alloc() family of functions allocates a handler, and that handler is the thing that processes requests coming into an HTTP server. On success, a pointer to the handler gets stored at the location pointed to by hp. slay.

Every single handler has a Request-URI it refers to, and that's determined by the path argument. Only the path component of the Request URI is considered when deciding whether the handler should be called. ikyk.

Also, each handler has a method it's registered to handle (default is GET, see nng_http_handler_set_method()), and optionally a 'Host' header it can be matched against (see nng_http_handler_set_host()).

And in some cases a handler may reference a logical tree (a directory) rather than just a single element. (See nng_http_handler_set_tree().) it's giving "one handler, whole vibe."

🎀 Custom Handler

The generic (first) form creates a handler that uses a user-supplied function to process HTTP requests. That function uses the asynchronous I/O framework, and it takes a pointer to an nng_aio structure.

The aio gets passed in with these input values (you retrieve them with nng_aio_get_input()):

1. nng_http_req * request — the client's HTTP request. 💌
2. nng_http_handler * handler — pointer to the handler object.
3. nng_http_conn * conn — the underlying HTTP connection.

The handler should create an nng_http_res * response (like, via nng_http_res_alloc() or nng_http_res_alloc_error()) and store that as the first output (index 0) with nng_aio_set_output().

Alternatively — plot twist — the handler may send the HTTP response (plus any associated body data) itself using the connection. In that case the output at index 0 of the aio should be NULL.

Finally, using the nng_aio_finish() function, the aio should be completed successfully. If any non-zero status gets returned back to the caller instead, then a generic 500 response will be created and sent, if possible, and the connection will be closed. 💀 rough.

The aio may be scheduled for deferred completion using the nng_aio_defer() function.

📌 Note: the callback function should NOT call nng_aio_begin(), because that will already have been done by the server framework. don't double-dip bestie.

🌈 Directory Handler

The second member of this family, nng_http_handler_alloc_directory(), creates a handler configured to serve a directory tree. The uri is taken as the root, and files are served from the directory tree rooted at path.

When the client Request-URI resolves to a directory in the file system, the handler looks first for a file named index.html or index.htm. If one is found, that file is returned back to the client. If no such index file exists, then an NNG_HTTP_STATUS_NOT_FOUND (404) error is sent back to the client. 😭

The Content-Type will be set automatically based upon the extension of the requested file name. If a content type cannot be determined from the extension, then application/octet-stream is used.

The directory handler is created as a tree handler initially in exclusive mode (see nng_http_handler_set_tree_exclusive). This can be changed by calling nng_http_handler_set_tree(3http) after creating the directory handler.

🧚 File Handler

The third member of this family, nng_http_handler_alloc_file(), creates a handler to serve up a single file; it does not traverse directories or search for index.html or index.htm files. one file, one job, periodt.

The Content-Type will be set automatically based upon the extension of the requested file name. If a content type cannot be determined from the extension, then application/octet-stream is used.

👑 Redirect Handler

The fourth member arranges for a server redirect from one URL to another. The reply will be with status code status, which should be a 3XX code such as 301, and a Location: header will contain the URL referenced by location, with any residual suffix from the request URI appended.

💡 Tip: use nng_http_handler_set_tree() to redirect an entire tree. For example, it's possible to redirect an entire HTTP site to another HTTPS site by specifying / as the path and then using the base of the new site, such as https://newsite.example.com as the new location. obsessed with how clean that is.

💡 Tip: be sure to use the appropriate value for status. Permanent redirection should use 301 and temporary redirections should use 307. In REST APIs, using a redirection to supply the new location of an object created with POST should use 303. choose wisely bestie ✨

⭐ Static Handler

The fifth member of this family, nng_http_handler_alloc_static(), creates a handler to serve up fixed content located in program data. The client is sent the data, with Content-Length of size bytes, and Content-Type of content_type. baked right in, no filesystem required 💖

🔥 RETURN VALUES

These functions return 0 on success, and non-zero otherwise. simple as.

😭 ERRORS

• NNG_EINVAL — an invalid path was specified. 🚩
• NNG_ENOMEM — insufficient free memory exists to allocate a message.
• NNG_ENOTSUP — no support for HTTP in the library. 💀

🌟 SEE ALSO

nng_aio_defer(3), nng_aio_finish(3), nng_aio_get_input(3), nng_aio_set_output(3), nng_http_handler_collect_body(3http), nng_http_handler_free(3http), nng_http_handler_set_host(3http), nng_http_handler_set_method(3http), nng_http_handler_set_tree(3http), nng_http_handler_set_tree_exclusive(3http), nng_http_res_alloc(3http), nng_http_res_alloc_error(3http), nng_http_server_add_handler(3http), nng_strerror(3), nng_aio(5), nng(7)

---

and that's the page! mwah 💋 this one's from the NNG Reference Manual, page NNG_HTTP_HANDLER_ALLOC(3http), dated 2026-01-13 — go build something iconic with it bestie 🫶✨