koatty_serve

library3.2.0jsnpmunverified

koatty_serve is a high-performance single-protocol server framework for Koatty, providing unified HTTP, HTTPS, HTTP/2, HTTP/3 (QUIC), WebSocket, WebSocket Secure, and gRPC server support. Version 3.2.0, released in 2024, features a template method pattern architecture with BaseServer, protocol-specific connection pools, graceful shutdown, health checks, and performance monitoring. It is designed for Node.js 18+ and ships with TypeScript types. Key differentiators include a unified configuration system via ConfigHelper, hot-reload capability, and per-instance single-protocol design.

devops

npm install koatty_serve

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOATTY_SERVE

koatty_serve

devopsjavascriptv3.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NewServe

✓ import { NewServe } from 'koatty_serve'

✗ const NewServe = require('koatty_serve').NewServe

ESM-only; CommonJS require is not supported.

HttpServer

✓ import { HttpServer } from 'koatty_serve'

✗ import { HttpServer } from 'koatty_serve/http'

Protocol-specific server classes are exported from the main package, not subpaths.

ConfigHelper

✓ import { ConfigHelper } from 'koatty_serve/config'

✗ import { ConfigHelper } from 'koatty_serve'

ConfigHelper is exported from a separate module to avoid loading Node.js-specific dependencies in browser environments.

BaseServer

✓ import { BaseServer } from 'koatty_serve'

✗ import { BaseServer } from 'koatty_serve/base'

BaseServer is available from the main package.

Creates an HTTP server using the recommended NewServe factory function with basic configuration.

import { NewServe } from "koatty_serve"; import { KoattyApplication } from "koatty_core"; const app = new KoattyApplication(); const httpServer = NewServe(app, { hostname: '127.0.0.1', port: 3000, protocol: 'http' }); httpServer.Start(() => { console.log('HTTP server started on http://127.0.0.1:3000'); });

Debug

Known issues

breakingIn v3.0.0, the server architecture changed from multi-protocol to single-protocol per instance. The old 'multiprotocol: true' configuration is removed.

fix

Use separate server instances for each protocol (HTTP, gRPC, WebSocket) instead of a single combined server.

affects: <3.0.0

deprecatedDirect instantiation of server classes (e.g., new HttpServer()) is deprecated in favor of the NewServe factory function, which handles configuration normalization and dependency injection.

fix

Use NewServe(app, config) instead of constructing server classes directly.

affects: >=3.0.0

gotchaConfigHelper.createHttpConfig() and similar methods accept partial config, but missing required fields like 'port' or 'protocol' will not error until serverStart is called.

fix

Validate configuration objects against the exported TypeScript types before passing to ConfigHelper or NewServe.

affects: >=3.0.0

breakingNode.js engines requirement increased to >=18.0.0 in v3.0.0, dropping support for Node 16 and below.

fix

Upgrade Node.js to version 18 or later.

affects: <3.0.0

gotchaWhen using HTTPS or HTTP/3 servers, SSL key and cert files must be provided with absolute paths or relative to process.cwd(). Relative paths may break if the application is run from a different directory.

fix

Resolve SSL file paths using path.resolve(__dirname, 'ssl/key.pem') to ensure correct location.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'koatty_serve/config'

The import path for ConfigHelper is incorrect; some might try 'koatty_serve/config' but the module resolution fails due to bundler or Node.js module resolution.

fix

Ensure you have the latest version installed and that your bundler (e.g., webpack, esbuild) supports package exports. For Node.js, use ESM with 'import { ConfigHelper } from 'koatty_serve/config';'

TypeError: NewServe is not a function

Incorrect import style: using CommonJS require() while the package is ESM-only, or importing from a subpath that does not export NewServe.

fix

Use the ESM import syntax: 'import { NewServe } from 'koatty_serve';'

Error: listen EADDRINUSE: address already in use :::3000

Trying to start two server instances on the same port, possibly due to attempting multi-protocol on single instance.

fix

Ensure each server instance uses a unique port. For HTTP and HTTPS, use separate ports or combine them via a reverse proxy.

Error: The 'protocol' property is required in 'options' for NewServe

Missing or misspelled 'protocol' field in the configuration object passed to NewServe.

fix

Add a valid protocol value (e.g., 'http', 'https', 'grpc', 'ws', 'wss', 'http2', 'http3') to the options object.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/koatty/koatty_serve ↗

packagekoatty_serve ↗

homepagehttps://github.com/koatty/koatty_serve ↗