diff --git a/license b/license new file mode 100644 index 0000000..40e0dda --- /dev/null +++ b/license @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Task Venture Capital GmbH + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/package.json b/package.json index 28cd75d..7a4468d 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,10 @@ { "name": "@losslessone_private/nullresolve", "version": "1.0.31", - "description": "The nullresolve project is a private service designed to handle requests that would otherwise remain unserved, providing appropriate feedback mechanisms within the servzone architecture.", + "description": "A serve.zone fallback response service for requests that would otherwise remain unserved.", "type": "module", - "author": "Lossless GmbH", - "license": "UNLICENSED", + "author": "Task Venture Capital GmbH", + "license": "MIT", "scripts": { "test": "(tstest test/)", "start": "(node cli.js)", diff --git a/readme.md b/readme.md index f4f9b84..e95a720 100644 --- a/readme.md +++ b/readme.md @@ -1,166 +1,154 @@ -# @losslessone_private/nullresolve +# nullresolve -The nullresolve is a robust service designed to manage and handle requests effectively within the servzone architecture. It ensures requests that would normally remain unserved receive appropriate handling and feedback. +`nullresolve` is the serve.zone fallback response service for requests that reach the edge but cannot be served by an application backend, upstream origin, DNS path, or security policy. + +## Issue Reporting and Security + +For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. + +## What It Does + +Instead of returning a raw proxy error, `nullresolve` serves clear HTML status pages through `@api.global/typedserver`'s `InfoHtml` helper. It is designed to be the last stop in a routing chain: if nothing else can answer, this service gives the client a controlled response. + +Typical uses: + +- unmatched or unassigned route fallback +- explicit status pages for blocked IPs and firewall events +- Cloudflare-style `5xx`, `1xxx`, WAF, country, attack, and Always Online status pages +- simple custom HTML info pages from query parameters + +## Package Status + +The current package name in `package.json` is still `@losslessone_private/nullresolve`, but the service belongs to the serve.zone workspace and is documented here as `nullresolve`. Do not rename the package in consuming code unless the package metadata changes. ## Install -To install the `@losslessone_private/nullresolve` package, it is essential to first set up a proper environment for handling private npm packages due to its private nature. This can be achieved through npm or yarn, which are both suitable JavaScript package managers. +In this workspace, install dependencies with pnpm and run package scripts from the repo root. -### Step-by-Step Installation: - -1. **Ensure you are logged into npm** with sufficient permissions to access private packages: - ```bash - npm login - ``` - Authentication is necessary for accessing private modules like `@losslessone_private/nullresolve`. - -2. **Install Using npm:** - ```bash - npm install @losslessone_private/nullresolve - ``` - If you are using a specific registry for your company or project, make sure to specify it in your npm configuration. - -3. **Install Using Yarn:** - ```bash - yarn add @losslessone_private/nullresolve - ``` - -After these steps, the module should be ready for use in your JavaScript or TypeScript project. - -## Usage - -The purpose of `nullresolve` is pivotal within a network ecosystem, particularly one that interfaces directly with user requests and external resources. Below, a comprehensive guide exists to demonstrate effective usage of this module within applications. - -### Quick Start Example - -Initialization and launching of a nullresolve service can be done succinctly: - -```typescript -// Import the NullResolve class from the package -import { NullResolve } from '@losslessone_private/nullresolve'; - -// Create an instance of NullResolve -const myNullResolveService = new NullResolve(); - -// Start the service -myNullResolveService.start().then(() => { - console.log('NullResolve service is running!'); -}).catch((error) => { - console.error('Error starting NullResolve service:', error); -}); - -// Stop the service gracefully -process.on('SIGINT', async () => { - await myNullResolveService.stop(); - console.log('NullResolve service stopped.'); - process.exit(0); -}); +```bash +pnpm install ``` -### Detailed Guide: Handling Requests and Custom Routes +For internal registry consumption using the current package name: -`nullresolve` can swiftly handle complex request scenarios utilizing its robust framework. Here's a detailed example of setting up custom handler routes that can respond with various HTTP statuses or custom messages based on the request: +```bash +pnpm add @losslessone_private/nullresolve +``` + +## Quick Start ```typescript import { NullResolve } from '@losslessone_private/nullresolve'; -// Initialize the service -const myService = new NullResolve(); - -// Start the service with custom routes -myService.serviceServer.addCustomRoutes(async (server) => { - server.addRoute( - '/error/:code', - new plugins.typedserver.servertools.Handler('GET', async (req, res) => { - let message; - switch (req.params.code) { - case '404': - message = 'This resource was not found.'; - break; - case '500': - message = 'Internal Server Error. Please try later.'; - break; - default: - message = 'An unexpected error occurred.'; - } - res.status(200).send(`

${message}

`); - }) - ); -}); - -// Activating the service -myService.start().then(() => { - console.log('Custom route service started.'); -}).catch((err) => { - console.error('Error while starting the service:', err); -}); -``` - -### Integrating Logging and Monitoring - -Given the mission-critical nature of services like `nullresolve`, reliable logging is indispensable to monitor activities and diagnose issues swiftly. This is integrated by default using the `smartlog` module for robust logging capabilities: - -```typescript -import { logger } from './nullresolve.logging.js'; - -// Utilize the logger for tracking and problem-solving -logger.info('Service Log: nullresolve service initiated'); -logger.warn('Warning Log: Potential issue detected'); -logger.error('Error Log: An error occurred in service operation'); -``` - -### Advanced Configuration - -For systems requiring specialized setups, nullresolve offers configurability through both code and external configuration objects: - -```typescript -// Customize through code -const config = { - domain: 'customdomain.com', +const service = new NullResolve({ port: 8080, - routes: [ - { - method: 'GET', - path: '/status/check', - handler: async (req, res) => { - res.status(200).send('Service is operational.'); - } - } - ] -}; + serviceDomain: 'nullresolve.example.com', +}); -myService.configure(config); +await service.start(); -// Running the service with a new configuration -myService.start(); -``` - -### Graceful Shutdown and Resource Management - -Services such as the one provided by `nullresolve` must incorporate mechanisms to stop gracefully, allowing them to release resources and finish current tasks before complete termination: - -```typescript -process.on('SIGTERM', async () => { - logger.info('Service is stopping gracefully.'); - await myService.stop(); - logger.info('Service has been successfully stopped.'); +process.once('SIGTERM', async () => { + await service.stop(); process.exit(0); }); ``` -### Custom Error Handling Strategies - -It is often beneficial to ensure that the service reacts gracefully during unexpected shutdowns or errors. Here's an example of implementing a strategy for error handling: +The package also exports CLI-style singleton helpers: ```typescript -const handleCriticalError = (err: Error) => { - logger.error(`Critical Error: ${err.message}`); - process.exit(1); -}; +import { runCli, stop } from '@losslessone_private/nullresolve'; -process.on('unhandledRejection', handleCriticalError); -process.on('uncaughtException', handleCriticalError); +await runCli(); +await stop(); ``` -By deploying `nullresolve` strategically within your infrastructure, it can transform how unhandled requests and errors are addressed, providing comprehensive protection and valuable insights into system status and health. This guide should serve to ensure effective deployment, utilization, and management of this sophisticated null service. -undefined \ No newline at end of file +## Routes + +`NullResolve.start()` creates a `UtilityServiceServer` and registers two custom routes. + +| Route | Purpose | +| --- | --- | +| `GET /status/:code` | Render a predefined status page. `:code` can be a normal HTTP status code or a named status template. | +| `GET /custom` | Render a status page from query parameters. | + +Named status templates currently handled by the service: + +| Code | Purpose | +| --- | --- | +| `ipblock` | IP allow/block policy response. | +| `firewall` | Firewall block response. | +| `500class` | Upstream/server error response placeholder. | +| `1000class` | DNS resolution failure placeholder. | +| `alwaysonline` | No cached copy / Always Online placeholder. | +| `waf` | Firewall challenge placeholder. | +| `country` | Country challenge placeholder. | +| `attack` | Under-attack challenge placeholder. | + +Examples: + +```text +/status/404 +/status/ipblock +/status/firewall +/custom?title=Maintenance&heading=Service%20Unavailable&text=Please%20try%20again%20later +``` + +## Configuration + +The public constructor options are intentionally small. + +```typescript +interface INullResolveOptions { + port?: number; + serviceDomain?: string; +} +``` + +| Option | Purpose | +| --- | --- | +| `port` | Optional port passed to the UtilityServiceServer. | +| `serviceDomain` | Service domain advertised to the UtilityServiceServer. Set this explicitly for new deployments. | + +`nullresolve.config.ts` currently contains the Sentry DSN used by `InfoHtml` status pages. + +## Operational Behavior + +- `start()` is idempotent while the server is already running. +- `stop()` is safe to call when the server has not been started. +- The service does not proxy, cache, or resolve upstream content; it only renders fallback HTML responses. +- The `serviceServer` property is exposed for inspection after startup, but route setup is internal to the class. + +## Development + +```bash +pnpm run build +pnpm test +pnpm start +``` + +Useful source entry points: + +- `ts/index.ts` exports `NullResolve`, `runCli()`, and `stop()`. +- `ts/nullresolve.classes.nullresolve.ts` defines options, server startup, and route behavior. +- `ts/nullresolve.config.ts` contains service-level status-page configuration. + +## License and Legal Information + +This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file. + +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. + +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein. + +Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar. + +### Company Information + +Task Venture Capital GmbH +Registered at District Court Bremen HRB 35230 HB, Germany + +For any legal inquiries or further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.