serve.zone/nullresolve
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh readme and legal info

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-07 20:22:12 +00:00
parent 9a0283b0a4
commit 7d4c81c00f
3 changed files with 154 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
license
+21
View File
@@ -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.
package.json
+3 -3
View File
@@ -1,10 +1,10 @@
{ {
"name": "@losslessone_private/nullresolve", "name": "@losslessone_private/nullresolve",
"version": "1.0.31", "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", "type": "module",
"author": "Lossless GmbH", "author": "Task Venture Capital GmbH",
"license": "UNLICENSED", "license": "MIT",
"scripts": { "scripts": {
"test": "(tstest test/)", "test": "(tstest test/)",
"start": "(node cli.js)", "start": "(node cli.js)",
readme.md
+127 -139
View File
@@ -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 ## 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 ```bash
npm login pnpm install
``` ```
Authentication is necessary for accessing private modules like `@losslessone_private/nullresolve`.
2. **Install Using npm:** For internal registry consumption using the current package name:
```bash ```bash
npm install @losslessone_private/nullresolve pnpm add @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. ## Quick Start
## 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);
});
```
### Detailed Guide: Handling Requests and Custom Routes
`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:
```typescript ```typescript
import { NullResolve } from '@losslessone_private/nullresolve'; import { NullResolve } from '@losslessone_private/nullresolve';
// Initialize the service const service = new NullResolve({
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(`<html><body><h1>${message}</h1></body></html>`);
})
);
});
// 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',
port: 8080, port: 8080,
routes: [ serviceDomain: 'nullresolve.example.com',
{ });
method: 'GET',
path: '/status/check',
handler: async (req, res) => {
res.status(200).send('Service is operational.');
}
}
]
};
myService.configure(config); await service.start();
// Running the service with a new configuration process.once('SIGTERM', async () => {
myService.start(); await service.stop();
```
### 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.exit(0); process.exit(0);
}); });
``` ```
### Custom Error Handling Strategies The package also exports CLI-style singleton helpers:
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:
```typescript ```typescript
const handleCriticalError = (err: Error) => { import { runCli, stop } from '@losslessone_private/nullresolve';
logger.error(`Critical Error: ${err.message}`);
process.exit(1);
};
process.on('unhandledRejection', handleCriticalError); await runCli();
process.on('uncaughtException', handleCriticalError); 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. ## Routes
undefined
`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.