vscode-budpl-ws

v2.4.0

Published

22 days ago

Web server for BUDPL manuals and local web server for VS Code Extension 'vscode-budpl'

Downloads

1,289

0High
0Medium
0Low

gofeht

localhost web server

vscode-budpl-ws

Local static-file web server used by the vscode-budpl VS Code extension to serve the BUDPL Programmer's Manual and the VS Code BUDPL Extension User's Guide. Designed to be spawned as a Node.js child process by the extension, but also usable as a stand-alone library.

Install

npm install

Pulls selfsigned, which is used to auto-generate a self-signed TLS certificate on the first HTTPS run.

Quick run (npm scripts)

npm run test         # plain HTTP at localhost:53248, root = C:/DATA/budpl/docREPO
npm run log          # same as test, plus log file and JSON comm file
npm run tlslog       # logging HTTPS variant (auto-generates a cert under the root on first run)
npm run test50k      # HTTP at port 50000
npm run tlsprod      # production HTTPS variant (auto-generates a cert under the root on first run)
npm run tlsprodcert  # production HTTPS variant with server certificate given in parameters

Or programmatically:

const ws = require("vscode-budpl-ws");
await ws.webServerStart(53248, "localhost", "C:/path/to/docroot");

Document routing — `docroute.json`

If <rootPath>/docroute.json exists and parses to an object whose values are existing readable directories, each entry registers an additional doctype namespace:

{
    "budplManual":    "C:/DATA/budpl/docHTMLpages/BUDPLManualHTML",
    "budplVSCEguide": "C:/DATA/budpl/docHTMLpages/BUDPLVSCEguideHTML"
}

URLs are routed by the first path segment: /budplManual/index.html is served from the budplManual directory, /budplVSCEguide/page.html from the budplVSCEguide directory. URLs without a recognized doctype segment fall back to the default budplManual doctype.

If docroute.json is missing, malformed, or has no usable entries, the whole rootPath is registered as the budplManual doctype.

Page lookup via `?only=` query string

In addition to the direct path/to/file.html form, a client can request a single HTML page through the catalog.json mapping by appending a ?only= query parameter to the URL path:

http://localhost:53248/budplManual/?only=xxx

How it is resolved:

The first path segment selects the doctype (here budplManual), exactly like for direct paths. Any segment is allowed before the ? — typical forms are /<docType>/ or /<docType>/index.html.
The first time a ? request hits a given doctype, the server reads <docroot>/catalog.json and builds an in-memory id-to-chapter map for that doctype.
The value of only (e.g. xxx) is looked up in that map. If a matching chapter entry is found, the server serves the file <docroot>/<chapter.fn>.<extension> it points to. If there is no match, no file is sent.

This is convenient for callers (e.g. the vscode-budpl extension) that know the catalog id of a chapter but not its on-disk filename, and lets the catalog absorb file renames without breaking links.

Other recognized query parameters — ref, tut, usg, thr — generate small routing pages that link to the chapter ids passed as repeated values; they share the same catalog lookup mechanism as only.

URL commands

A handful of paths starting with /! are intercepted before the normal file-serving logic and trigger control actions instead of returning a file. All commands are matched with === against the request URL — there must be no query string, no path segment, and no trailing slash.

| URL path | Method | Effect | Response body | |---|---|---|---| | /!ssttoopp | GET | Calls webServerStop() after responding, terminating the server. Useful when the user needs to shut down the server. It works only if the server has started with pibo_searchFreePort === true. | <html>... Server is closing... </html> | | /!test | GET | Liveness probe. Server stays running. The response includes the server's current timestamp, so a client can use it as a heartbeat. | <html>... <date> : Server is live! </html> | | /!whoIsThere | GET | Identity probe. Server stays running. Used by a starting instance during port search: if the requested port is already bound, the new instance hits this URL on the existing listener to check whether it is another vscode-budpl-ws (and not an unrelated server squatting on the port). | <html>... vscode-budpl-ws.<USERDOMAIN>.<USERNAME> ... </html> |

Example — stop the running server from a shell:

curl http://localhost:53248/!ssttoopp

Example — heartbeat:

curl http://localhost:53248/!test

These paths are reserved: do not place files or directories with these names in the document root, they would be unreachable.

HTTPS / TLS

Pass "https://" as the pistr_uriScheme argument. Three optional params control the cert/key:

pistr_tlsCertPath, pistr_tlsKeyPath — full paths to user-supplied PEM files.
pistr_tlsKeyPassphrase — passphrase for an encrypted private key.

Resolution rule:

If both pistr_tlsCertPath and pistr_tlsKeyPath are provided and both files exist, they are loaded directly.
Otherwise the server looks for vscode-budpl-ws.cert.pem and vscode-budpl-ws.key.pem under pistr_rootPath. If either is missing, a self-signed pair (CN=localhost, SAN=localhost+127.0.0.1, RSA-2048, sha256, 10-year validity) is generated, written, then loaded.

Browsers will warn "Your connection is not private" until the auto-generated cert is added to the OS trust store, or until you supply a CA-signed cert via the path parameters.

Exported functions

`webServerStart(piin_portNum, pistr_IP, pistr_rootPath?, pistr_uriScheme?, pibo_searchFreePort?, pibo_detailTracking?, pistr_logfilePath?, pistr_commFilePath?, pibo_printPermission?, pistr_tlsCertPath?, pistr_tlsKeyPath?, pistr_tlsKeyPassphrase?)` → `Promise<void>`

Starts the listener.

| Param | Type | Default | Description | |---|---|---|---| | piin_portNum | number | required | Starting port number. Free-port-search behavior is governed by pibo_searchFreePort. | | pistr_IP | string | required | Hostname or IP to bind to (e.g. "localhost", "127.0.0.1"). | | pistr_rootPath | string | "./" | Document root. Used to locate docroute.json and the auto-generated TLS cache. | | pistr_uriScheme | string | "http://" | "http://" or "https://". Controls plain HTTP vs TLS. | | pibo_searchFreePort | boolean | true | When true, if piin_portNum is reserved the function increments the port and retries until a free one is found (or the 65535 ceiling is hit). When false, a reserved piin_portNum causes an error message and immediate return — no port search, no attempt to stop a previous instance via /!ssttoopp. Set to false for production deployments where the port is fixed (e.g. behind a reverse proxy). | | pibo_detailTracking | boolean | false | When true, the server emits per-request tracking messages to the console and (if enabled) the log file — useful for debugging file search, catalog lookups, and request handling. When false, only startup, shutdown, and error messages are emitted. Independent of pibo_printPermission, which controls log-file writing in general. | | pistr_logfilePath | string | undefined | undefined | Optional full path to a log file (opened in append mode). | | pistr_commFilePath | string | undefined | undefined | Optional path to a JSON status file written for the parent process. | | pibo_printPermission | boolean | false | When true, verbose messages are printed into the log file. | | pistr_tlsCertPath | string | undefined | undefined | HTTPS only. See "HTTPS / TLS" above. | | pistr_tlsKeyPath | string | undefined | undefined | HTTPS only. See "HTTPS / TLS" above. | | pistr_tlsKeyPassphrase | string | undefined | undefined | HTTPS only. Passphrase for the user-supplied private key (ignored for auto-generated keys). |

Side effect when run as a child process: writes Listened port: ##<port>##. to stdout once the server is bound, so the parent can read the actual port off the captured stdout.

`webServerStop()` → `Promise<void>`

Gracefully closes the running server, terminates all open connections, and closes the log file (if one was opened). No-op if the server was not started.

`clientForTesting(pistr_TCPIP, pistr_path)` → `void`

Issues an HTTP GET to pistr_TCPIP + pistr_path, prints the streamed response body and final status code to stdout. Smoke-test helper; no return value.

`testlanc(pistr_uri)` → `Promise<void>`

Issues a liveness check (HEAD semantics) against pistr_uri and prints "testlanc OK" on success or the error to stderr.

Layout

vscode-budpl-ws.js — the module (CommonJS).
package.json — npm metadata + run scripts.
LICENSE — ISC.
README.md — this file.

License

ISC. See LICENSE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vscode-budpl-ws

Install

Quick run (npm scripts)

Document routing — docroute.json

Page lookup via ?only= query string

URL commands

HTTPS / TLS

Exported functions

webServerStart(piin_portNum, pistr_IP, pistr_rootPath?, pistr_uriScheme?, pibo_searchFreePort?, pibo_detailTracking?, pistr_logfilePath?, pistr_commFilePath?, pibo_printPermission?, pistr_tlsCertPath?, pistr_tlsKeyPath?, pistr_tlsKeyPassphrase?) → Promise<void>

webServerStop() → Promise<void>

clientForTesting(pistr_TCPIP, pistr_path) → void

testlanc(pistr_uri) → Promise<void>

Layout

License

Document routing — `docroute.json`

Page lookup via `?only=` query string

`webServerStart(piin_portNum, pistr_IP, pistr_rootPath?, pistr_uriScheme?, pibo_searchFreePort?, pibo_detailTracking?, pistr_logfilePath?, pistr_commFilePath?, pibo_printPermission?, pistr_tlsCertPath?, pistr_tlsKeyPath?, pistr_tlsKeyPassphrase?)` → `Promise<void>`

`webServerStop()` → `Promise<void>`

`clientForTesting(pistr_TCPIP, pistr_path)` → `void`

`testlanc(pistr_uri)` → `Promise<void>`