ndc

HTTP(S) + WS(S) + Terminal MUX

A cross-platform C library for building network daemons - HTTP servers, WebSocket servers, telnet-like services, terminal multiplexers, or custom network applications.

From NeverDark • Powers tty.pt

What is ndc?

libndc - C library for building network daemons
ndc - Standalone server binary with HTTP/WS/terminal mux

Build telnet-like servers, custom protocol handlers, HTTP APIs, WebSocket apps, or anything that needs persistent network connections with an event loop.

Platform Support

| Platform | Status | |----------|--------| | Linux, macOS, BSD | ✅ Full support | | Windows | ⚠️ HTTP/WS only (no PTY/CGI/privilege dropping) |

Quick Start

# Run simple HTTP server
ndc -d -p 8888

# With SSL (POSIX)
sudo ndc -C . -K certs.txt -d

Command Line Options

| Option | Description | |--------|-------------| | -p PORT | Specify HTTP server port | | -s PORT | Specify HTTPS server port (POSIX) | | -C PATH | Change directory to PATH before starting | | -K PATH | Load SSL certificate mappings from file (POSIX) | | -k CERT | Add single SSL certificate mapping (POSIX) | | -d | Don't detach (run in foreground) | | -r | Root multiplex mode | | -? | Display help message |

certs.txt Format (POSIX)

example.com:cert.pem:key.pem

Building Custom Daemons

Minimal Example

#include <ttypt/ndc.h>

int main(void) {
    ndc_config.port = 8080;
    ndc_register("GET", do_GET, CF_NOAUTH);
    return ndc_main();  // Blocks, runs event loop
}

Telnet-Style Server

void cmd_echo(socket_t fd, int argc, char *argv[]) {
    for (int i = 0; i < argc; i++)
        ndc_writef(fd, "%s ", argv[i]);
    ndc_writef(fd, "\n");
}

int ndc_connect(socket_t fd) {
    ndc_writef(fd, "Welcome! Type 'echo hello'\n");
    return 1;  // Accept connection
}

int main(void) {
    ndc_config.port = 2323;
    ndc_register("echo", cmd_echo, CF_NOAUTH);
    return ndc_main();
}

Custom Protocol Handler

void my_handler(socket_t fd, char *body) {
    // Handle raw data from client
    ndc_write(fd, "RESPONSE", 8);
}

void ndc_command(socket_t fd, int argc, char *argv[]) {
    // Called on every command
    log_command(argv[0]);
}

void ndc_update(unsigned long long dt) {
    // Periodic tick (game loops, etc)
}

Library API

Core Functions

| Function | Description | Return Value | |----------|-------------|--------------| | ndc_main() | Start event loop (blocking) | Exit code | | ndc_register(name, cb, flags) | Register command handler | - | | ndc_register_handler(path, handler) | Register HTTP handler for exact path | - | | ndc_write(fd, data, len) | Write raw bytes | Bytes written or -1 | | ndc_writef(fd, fmt, ...) | Write formatted data | Bytes written or -1 | | ndc_dwritef(fd, fmt, va) | Write formatted data with va_list | Bytes written or -1 | | ndc_close(fd) | Close connection | - | | ndc_wall(msg) | Broadcast message to all descriptors | - |

HTTP Functions

| Function | Description | Return Value | |----------|-------------|--------------| | ndc_header(fd, key, val) | Add response header (call before ndc_head) | - | | ndc_head(fd, code) | Send HTTP status and headers | - | | ndc_body(fd, body) | Send body and close connection | - | | ndc_sendfile(fd, path) | Serve static file with auto MIME type | - | | ndc_status_text(code) | Get HTTP status text for code | Status string |

Descriptor Functions

| Function | Description | Return Value | |----------|-------------|--------------| | ndc_flags(fd) | Get descriptor flags | Flags bitmask | | ndc_set_flags(fd, flags) | Set descriptor flags | - |

Request Environment Functions

| Function | Description | Return Value | |----------|-------------|--------------| | ndc_env_get(fd, target, key) | Get request environment value | 0 on success | | ndc_env_put(fd, key, value) | Set environment key/value | 0 on success | | ndc_env_clear(fd) | Clear request environment | - | | ndc_env(fd) | Get internal env handle (advanced) | Env handle |

POSIX-Only Functions

| Function | Description | Return Value | |----------|-------------|--------------| | ndc_pty(fd, args[]) | Spawn PTY-backed command | - | | ndc_exec(fd, args[], cb, input, len) | Execute command with callback | - | | ndc_auth(fd, username) | Mark user as authenticated, drop privileges (POSIX) | 0 on success, 1 on failure | | ndc_cert_add(str) | Add cert mapping: domain:cert.pem:key.pem | - | | ndc_certs_add(fname) | Load certificate mappings from file | - | | ndc_mmap(mapped, file) | Map file into memory | File size or -1 | | ndc_mmap_iter(start, pos) | Iterate mapped lines separated by \n | Next line or NULL | | ndc_sendfile(fd, path) | Serve static file (POSIX uses sendfile syscall) | - |

Built-in Command Handlers

| Handler | Description | |---------|-------------| | do_GET | HTTP GET request handler | | do_POST | HTTP POST request handler | | do_sh | Shell PTY handler (POSIX-only) |

Hook Functions (Optional)

Define these weak symbol hooks to customize behavior:

| Hook | Description | Return Value | |------|-------------|--------------| | ndc_connect(socket_t fd) | Accept/reject WebSocket connections | Non-zero to accept | | ndc_disconnect(socket_t fd) | Cleanup on disconnect | - | | ndc_accept(socket_t fd) | Called on socket accept | Ignored | | ndc_command(socket_t fd, int argc, char *argv[]) | Before command execution | - | | ndc_flush(socket_t fd, int argc, char *argv[]) | After command execution | - | | ndc_vim(socket_t fd, int argc, char *argv[]) | Called when command not found | - | | ndc_update(unsigned long long dt) | Periodic updates (dt in milliseconds) | - | | ndc_auth_check(socket_t fd) | Custom auth hook: validate credentials, return username. Default: session file lookup in ./sessions/ | Username string or NULL |

Example:

int ndc_connect(socket_t fd) {
    ndc_writef(fd, "Welcome!\n");
    return 1;  // Accept connection
}

void ndc_disconnect(socket_t fd) {
    // Cleanup resources
}

void ndc_command(socket_t fd, int argc, char *argv[]) {
    // Log or validate commands
}

void ndc_flush(socket_t fd, int argc, char *argv[]) {
    // Post-command processing
}

void ndc_vim(socket_t fd, int argc, char *argv[]) {
    ndc_writef(fd, "Unknown command: %s\n", argv[0]);
}

void ndc_update(unsigned long long dt) {
    // Game loop, periodic tasks, etc.
}

char *ndc_auth_check(socket_t fd) {
    // Check cookies, tokens, etc.
    // Return username or NULL
    return authenticated_user;
}

Configuration

struct ndc_config {
    char *chroot;                    // chroot directory (POSIX)
    unsigned flags;                  // Server flags (see below)
    unsigned port;                   // HTTP listen port
    unsigned ssl_port;               // HTTPS listen port (POSIX)
    ndc_handler_t *default_handler;  // Fallback HTTP handler
};

// Example usage
ndc_config.port = 8080;              // HTTP on port 8080
ndc_config.ssl_port = 8443;          // HTTPS on port 8443 (POSIX)
ndc_config.flags = NDC_SSL;          // Enable TLS
ndc_config.chroot = "/var/www";      // chroot directory (POSIX)
ndc_config.default_handler = my_404; // Custom 404 handler

Server Flags

| Flag | Description | |------|-------------| | NDC_WAKE | Wake on activity | | NDC_SSL | Enable TLS/SSL | | NDC_ROOT | Root multiplex mode | | NDC_SSL_ONLY | Redirect HTTP to HTTPS when SSL enabled | | NDC_DETACH | Detach into background (daemon mode) |

Command Flags

Use with ndc_register():

| Flag | Description | |------|-------------| | CF_NOAUTH | Allow command without authentication | | CF_NOTRIM | Do not trim trailing CR from input |

Descriptor Flags

Access with ndc_flags() and ndc_set_flags():

| Flag | Description | |------|-------------| | DF_CONNECTED | Connection established and accepted | | DF_WEBSOCKET | WebSocket mode enabled | | DF_TO_CLOSE | Marked to close after remaining output | | DF_ACCEPTED | Accepted socket (pre-WebSocket) | | DF_AUTHENTICATED | User authenticated |

POSIX vs Windows

| Feature | POSIX | Windows | |---------|-------|---------| | HTTP/WebSocket | ✅ | ✅ | | Custom commands | ✅ | ✅ | | PTY/Terminal | ✅ | ❌ | | CGI execution | ✅ | ❌ | | Authentication (privilege dropping) | ✅ | ❌ | | SSL certs | ✅ | ❌ |

Windows build provides core networking only.

CGI & Static Files (POSIX)

Create index.sh for dynamic pages:

#!/bin/sh
# CGI scripts output status line without "HTTP/1.1" prefix
printf "200 OK\r\n"
printf "Content-Type: text/plain\r\n"
printf "\r\n"
printf "Hello world\n"
printf "REQUEST_METHOD=%s\n" "$REQUEST_METHOD"
printf "QUERY_STRING=%s\n" "$QUERY_STRING"

Control access with serve.allow and serve.autoindex files.

NPM for Web Terminal

Install the package:

npm install @tty-pt/ndc

JavaScript/TypeScript API:

import { create } from "@tty-pt/ndc";

// Create terminal instance
const term = create(document.getElementById("terminal"), {
  proto: "ws",        // or "wss" for secure
  port: 4201,
  sub: {
    onOpen: (term, ws) => {
      console.log("Connected to server");
    },
    onClose: (ws) => {
      console.log("Disconnected, reconnecting...");
    },
    onMessage: (ev, arr) => {
      // Return true to continue default processing
      return true;
    },
    cols: 80,
    rows: 25,
  },
  debug: false,
});

See types/ndc.d.ts for full TypeScript definitions.

Documentation

• Man pages: man ndc and man ndc.3
• Full API: include/ttypt/ndc.h
• Examples: src/test-*.c

Plugin System

Load dynamic modules with dependency resolution via libndx:

// In your plugin module
const char *ndx_deps[] = { "dependency.so", NULL };

// In main application
ndx_load("plugin.so");  // Automatically loads dependencies

The binary automatically loads core.so at startup. Plugins can hook into lifecycle events (ndc_update, ndc_connect, etc.) to extend functionality.

Installation: See install docs
Entry points: src/ndc.c (native), ndc-cli.js (npm)