Pixl Server Daemon Framework

Common errors

• Error: Cannot find module 'pixl-server-web'

  cause A required component module has not been installed via npm.
  fix Run `npm install pixl-server-web` (or the specific missing component) in your project directory.

• Error: listen EADDRINUSE: address already in use :::8080

  cause The configured port for the server is already in use by another process.
  fix Change the `http_port` in your server's configuration to an available port, or stop the conflicting process. For privileged ports (e.g., 80), ensure no other web server is running.

• Server starts but web content is not served or 404s for static files.

  cause The `http_htdocs_dir` configuration for `pixl-server-web` is incorrect, or the files are missing/have incorrect permissions.
  fix Verify that `http_htdocs_dir` points to the correct absolute path where your static files reside, and ensure the Node.js process has read access to that directory and its contents.

Warnings

• gotcha The order of components in the `components` array matters. Components that depend on others (e.g., `pixl-server-api` depends on `pixl-server-web`) must be listed after their dependencies to ensure proper initialization.
  Fix: Arrange components in the `components` array according to their dependencies, ensuring foundational components are listed first.
• gotcha Configuration can be overridden by multiple sources (config files, command-line arguments, environment variables). Understanding this hierarchy is crucial to avoid unexpected behavior, as settings can be silently overwritten.
  Fix: Review the configuration documentation to understand the precedence of different config sources. Use debug logging (`debug_level: 9`) to inspect the final merged configuration.
• gotcha A basic Pixl-Server instance without any components will not perform any useful tasks. Developers must explicitly `require()` and add components to the `components` array to extend functionality.
  Fix: Always include relevant components (e.g., `pixl-server-web`, `pixl-server-api`) in the server's `components` array based on the desired functionality.
• gotcha When using `pixl-server-web` (or any component binding to a port), listening on privileged ports (below 1024, like 80 or 443) typically requires root privileges. Running Node.js processes as root is a security risk.
  Fix: Use a non-privileged port (e.g., 8080) for your server, or use a reverse proxy (like Nginx) to forward requests from privileged ports to your application's non-privileged port.
• breaking Based on the provided release history and documentation, there are no explicitly documented breaking API changes within the 1.x major version of `pixl-server` itself. Breaking changes primarily apply to specific `pixl-server-*` components or their upstream dependencies.
  Fix: N/A

Install

• npm install pixl-server npm
• yarn add pixl-server yarn
• pnpm add pixl-server pnpm

Imports

• PixlServer
  wrong:

  import PixlServer from 'pixl-server';

  correct:

  const PixlServer = require('pixl-server');

  The core server class. Pixl-server is a CommonJS module and primarily uses `require()` for module loading.
• WebServerComponent
  wrong:

  import { WebServer } from 'pixl-server-web';

  correct:

  const WebServer = require('pixl-server-web');

  Example of loading a component module. Components are typically required and passed directly into the `components` array during server instantiation.
• APIComponent
  wrong:

  import PixlServerAPI from 'pixl-server-api';

  correct:

  require('pixl-server-api')

  Illustrates the pattern for including any of the many available `pixl-server-*` component modules in the server's `components` array. No variable assignment is strictly needed if directly within the array.

Quickstart

This quickstart demonstrates how to initialize a Pixl-Server instance, integrate the `pixl-server-web` component to serve static files, and handle graceful shutdown. It sets up a basic web server listening on port 8080, serving an 'index.html' from a local 'www' directory.

const PixlServer = require('pixl-server');
const path = require('path');
const fs = require('fs');

// Create dummy directories for demonstration
const logDir = path.join(__dirname, 'log');
const htdocsDir = path.join(__dirname, 'www');

if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
if (!fs.existsSync(htdocsDir)) fs.mkdirSync(htdocsDir, { recursive: true });
fs.writeFileSync(path.join(htdocsDir, 'index.html'), '<h1>Hello from Pixl-Server!</h1>');

let server = new PixlServer({
	__name: 'MyWebServer',
	__version: "1.0.50",
	config: {
		"log_dir": logDir, // Use local log directory
		"debug_level": 9,
		
		"WebServer": {
			"http_port": 8080, // Use a non-privileged port
			"http_htdocs_dir": htdocsDir, // Use local htdocs directory
			"http_ip_address": "127.0.0.1" // Explicitly bind to localhost
		}
	},
	
	components: [
		require('pixl-server-web')
	]
	
});

server.startup( function(err) {
	if (err) {
		console.error("Server startup failed:", err);
		process.exit(1);
	}
	console.log(`MyWebServer v${server.__version} started on http://127.0.0.1:8080`);
	console.log(`Serving static files from: ${htdocsDir}`);
	console.log("Press Ctrl+C to stop the server.");
	
	// Handle graceful shutdown
	process.on('SIGINT', () => {
		console.log("\nShutting down server...");
		server.shutdown(() => {
			console.log("Server shut down gracefully.");
			process.exit(0);
		});
	});
} );