instaserve 1.0.21 → 1.1.2

package/README.md

@@ -0,0 +1,176 @@
+<div align="center">
+  <h1 style="color: #3b82f6; margin: 10px 0 5px;">Instaserve</h1>
+  <p style="color: #6b7280; margin: 0;">Instant web stack for Node.js</p>
+  
+  <p>
+    <img src="https://img.shields.io/npm/v/instaserve" alt="npm version" />
+    <img src="https://img.shields.io/bundlephobia/minzip/instaserve" alt="bundle size" />
+  </p>
+</div>
+
+## Usage
+
+<div style="background: white; padding: 15px; border-radius: 6px; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1); margin: 15px 0;">
+  <pre style="margin: 0;"><code>npx instaserve [options]
+npx instaserve generate-routes</code></pre>
+</div>
+
+## Commands
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">generate-routes</code>
+  <span>Create a sample routes.js file in the current directory</span>
+</div>
+
+## Options
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-port &lt;number&gt;</code>
+  <span>Port to listen on (default: 3000)</span>
+</div>
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-ip &lt;address&gt;</code>
+  <span>IP address to bind to (default: 127.0.0.1)</span>
+</div>
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-public &lt;path&gt;</code>
+  <span>Public directory path (default: ./public)</span>
+</div>
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-api &lt;file&gt;</code>
+  <span>Path to routes file (default: ./routes.js)</span>
+</div>
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-secure</code>
+  <span>Enable HTTPS (requires cert.pem and key.pem - run ./generate-certs.sh)</span>
+</div>
+
+<div style="display: flex; gap: 8px; margin: 8px 0;">
+  <code style="background: #f3f4f6; padding: 2px 4px; border-radius: 4px; color: #2563eb;">-help</code>
+  <span>Show help message</span>
+</div>
+
+## HTTPS Support
+
+Instaserve supports HTTPS with self-signed certificates. To enable HTTPS:
+
+1. **Generate certificates:**
+   ```bash
+   ./generate-certs.sh
+   ```
+   This creates `cert.pem` and `key.pem` files and adds them to your system's trust store.
+
+2. **Run with HTTPS:**
+   ```bash
+   npx instaserve -secure
+   ```
+
+The certificate generation script:
+- Creates a self-signed certificate valid for 365 days
+- Automatically adds the certificate to your system trust store (macOS/Linux)
+- Prevents browser security warnings
+
+## Routes
+
+The routes file (`routes.js` by default) defines your API endpoints. Each route is a function that handles requests to a specific URL path.
+
+### Generating a Routes File
+
+To create a sample `routes.js` file with example routes and middleware:
+
+```bash
+npx instaserve generate-routes
+```
+
+This creates a `routes.js` file in the current directory with example code. If the file already exists, the command will fail to prevent overwriting.
+
+### Routes File Validation
+
+Instaserve validates routes files on startup:
+- If `-api` is specified and the file doesn't exist, the server will fail to start
+- The routes file must export a default object
+- All route handlers must be functions
+- Invalid routes files will cause the server to exit with an error message
+
+### Basic Route Example
+
+```javascript
+export default {
+    // Handle GET /hello
+    hello: (req, res, data) => {
+        return { message: 'Hello World' }
+    }
+}
+```
+
+### Special Routes (Middleware)
+
+Routes starting with `_` are middleware functions that run on **every request** before the main route handler. They are useful for:
+
+- Logging requests
+- Authentication
+- Request modification
+- Response headers
+
+Middleware functions can:
+- Return `false` to continue to the next middleware or main route
+- Return a truthy value to stop processing and use that as the response
+- Modify the request or response objects
+
+#### Middleware Example
+
+```javascript
+export default {
+    // Log every request
+    _log: (req, res, data) => {
+        console.log(`${req.method} ${req.url}`)
+        return false // Continue processing
+    },
+
+    // Block unauthorized requests
+    _auth: (req, res, data) => {
+        if (!data.token) {
+            res.writeHead(401)
+            return 'Unauthorized'
+        }
+        return false // Continue if authorized
+    }
+}
+```
+
+### Route Parameters
+
+Each route function receives:
+- `req` - The HTTP request object
+- `res` - The HTTP response object
+- `data` - Combined data from:
+  - POST body (if JSON)
+  - URL query parameters
+  - Form data
+
+### Example Routes File
+
+```javascript
+// routes.js
+export default {
+    // Middleware example
+    _debug: (req, res, data) => {
+        console.log('Request:', req.url)
+        return false // Continue to next route
+    },
+
+    // API endpoint
+    api: (req, res, data) => {
+        return { status: 'ok', data }
+    },
+
+    // Error handling
+    testerror: () => {
+        throw new Error('Test error')
+    }
+}
+```

package/generate-certs.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+echo "Generating self-signed certificates for Instaserve..."
+
+# Create openssl config file
+cat > openssl.conf << EOF
+[req]
+distinguished_name = req_distinguished_name
+req_extensions = v3_req
+prompt = no
+
+[req_distinguished_name]
+C = US
+ST = State
+L = City
+O = Instaserve
+OU = Development
+CN = localhost
+
+[v3_req]
+basicConstraints = CA:FALSE
+keyUsage = nonRepudiation, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth, clientAuth
+subjectAltName = @alt_names
+
+[alt_names]
+DNS.1 = localhost
+DNS.2 = *.localhost
+IP.1 = 127.0.0.1
+IP.2 = ::1
+EOF
+
+# Generate private key
+openssl genrsa -out key.pem 2048
+
+# Generate certificate with config
+openssl req -new -x509 -key key.pem -out cert.pem -days 365 -config openssl.conf -extensions v3_req
+
+# Clean up config
+rm openssl.conf
+
+echo "Certificates generated: cert.pem and key.pem"
+
+# Add to system trust store (macOS)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    echo "Adding certificate to macOS trust store..."
+    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain cert.pem
+    echo "Certificate added to macOS trust store"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    echo "Adding certificate to Linux trust store..."
+    sudo cp cert.pem /usr/local/share/ca-certificates/instaserve.crt
+    sudo update-ca-certificates
+    echo "Certificate added to Linux trust store"
+else
+    echo "Please manually add cert.pem to your system's trust store"
+fi
+
+echo "HTTPS certificates ready! Use 'npx instaserve -secure' to enable HTTPS"
+echo "Note: You may still see browser warnings for self-signed certificates" 

package/instaserve

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import chalk from 'chalk'
+import fs from 'node:fs'
+
+console.log(chalk.cyan('\nInstaserve - Instant Web Stack\n'))
+console.log(chalk.yellow('Usage:'))
+console.log(chalk.green('  npx instaserve [options]'))
+console.log(chalk.green('  npx instaserve generate-routes\n'))
+console.log(chalk.yellow('Commands:'))
+console.log(chalk.green('  generate-routes') + '   Create a sample routes.js file in the current directory\n')
+console.log(chalk.yellow('Options:'))
+console.log(chalk.green('  -port <number>') + '    Port to listen on (default: 3000)')
+console.log(chalk.green('  -ip <address>') + '     IP address to bind to (default: 127.0.0.1)')
+console.log(chalk.green('  -public <path>') + '    Public directory path (default: ./public)')
+console.log(chalk.green('  -api <file>') + '       Path to routes file (default: ./routes.js)')
+console.log(chalk.green('  -secure') + '           Enable HTTPS (requires cert.pem and key.pem: run generate-certs.sh)')
+console.log(chalk.green('  -help') + '             Show this help message\n')
+
+if (process.argv.includes('-help')) {
+    process.exit(0)
+}
+
+const args = process.argv.slice(2)
+
+// Handle generate-routes command
+if (args[0] === 'generate-routes') {
+    const routesFile = './routes.js'
+    if (fs.existsSync(routesFile)) {
+        console.error(chalk.red(`Error: ${routesFile} already exists`))
+        process.exit(1)
+    }
+    
+    const sampleRoutes = `export default {
+    // Middleware functions (prefixed with _) run on every request
+    // Return false to continue processing, or a value to use as response
+    
+    // Example: Log all requests
+    _log: (req, res, data) => {
+        console.log(\`\${req.method} \${req.url}\`)
+        return false // Continue to next middleware or route
+    },
+
+    // Example: Basic authentication (commented out)
+    // _auth: (req, res, data) => {
+    //     if (!data.token) {
+    //         res.writeHead(401)
+    //         return 'Unauthorized'
+    //     }
+    //     return false // Continue if authorized
+    // },
+
+    // Regular route handlers
+    hello: (req, res, data) => {
+        return { message: 'Hello World' }
+    },
+
+    api: (req, res, data) => {
+        return { message: 'API endpoint', data }
+    }
+}
+`
+    
+    fs.writeFileSync(routesFile, sampleRoutes)
+    console.log(chalk.green(`✓ Created ${routesFile}`))
+    process.exit(0)
+}
+
+import server from './module.mjs'
+
+const params = {}
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('-')) {
+        const key = arg.slice(1)
+        const nextArg = args[i + 1]
+        if (nextArg && !nextArg.startsWith('-')) {
+            params[key] = nextArg
+            i++ // Skip the next argument since we used it
+        } else {
+            params[key] = true // Boolean flag
+        }
+    }
+}
+
+// Load routes file
+let routes = {}
+const routesFile = params.api || './routes.js'
+const routesFileSpecified = !!params.api
+
+if (routesFileSpecified && !fs.existsSync(routesFile)) {
+    console.error(chalk.red(`Error: Routes file "${routesFile}" does not exist`))
+    process.exit(1)
+}
+
+if (fs.existsSync(routesFile)) {
+    try {
+        const imported = await import(routesFile)
+        routes = imported.default || imported
+        
+        if (!routes || typeof routes !== 'object' || Array.isArray(routes)) {
+            console.error(chalk.red(`Error: Routes file "${routesFile}" must export a default object`))
+            process.exit(1)
+        }
+        
+        for (const [key, handler] of Object.entries(routes)) {
+            if (typeof handler !== 'function') {
+                console.error(chalk.red(`Error: Route "${key}" in "${routesFile}" must be a function`))
+                process.exit(1)
+            }
+        }
+    } catch (e) {
+        console.error(chalk.red(`Error: Could not load routes file "${routesFile}": ${e.message}`))
+        process.exit(1)
+    }
+}
+
+server(routes) 

package/module.mjs

@@ -0,0 +1,136 @@
+import http from 'node:http'
+import https from 'node:https'
+import fs from 'node:fs'
+
+const args = process.argv.slice(2)
+const params = {}
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('-')) {
+        const key = arg.slice(1)
+        const nextArg = args[i + 1]
+        if (nextArg && !nextArg.startsWith('-')) {
+            params[key] = nextArg
+            i++ // Skip the next argument since we used it
+        } else {
+            params[key] = true // Boolean flag
+        }
+    }
+}
+
+function public_file(r, s) {
+    if (r.url == '/') r.url = '/index.html'
+    const fn = `${params.public || './public'}${r.url.replace(/\.\./g, '')}`
+    if (fs.existsSync(fn)) {
+        const content = fs.readFileSync(fn, 'utf-8')
+        if (fn.match(/.js$/)) {
+            s.writeHead(200, { 'Content-Type': 'application/javascript' })
+        } else {
+            s.writeHead(200)
+        }
+        s.end(content)
+        return true // Indicate file was served
+    }
+    return false // Indicate no file was served
+}
+
+export default async function (routes, port = params.port || 3000, ip = params.ip || '127.0.0.1') {
+    const publicDir = params.public || './public'
+    if (publicDir.includes('..')) {
+        throw new Error('Public directory path cannot contain ".."')
+    }
+    if (!fs.existsSync(publicDir)) {
+        throw new Error(`Public directory "${publicDir}" does not exist`)
+    }
+
+    const requestHandler = async (r, s) => {
+        let sdata = '', rrurl = r.url || ''
+        let responseSent = false
+        
+        r.on('data', (s) => sdata += s.toString().trim())
+        r.on('end', (x) => {
+            try {
+                // Compose data object
+                const data = sdata ? JSON.parse(sdata) : {}
+                const qs = rrurl.split('?')
+                if(qs && qs[1]) {
+                    const o = JSON.parse('{"' + decodeURI(qs[1].replace(/&/g, "\",\"").replace(/=/g, "\":\"")) + '"}')
+                    Object.assign(data, o)
+                }
+
+                const midware = Object.keys(routes)
+                    .filter((k) => k.startsWith('_'))
+                    .find((k) => {
+                        const result = routes[k](r, s, data)
+                        if (result && !responseSent) {
+                            responseSent = true
+                            s.end(typeof result === 'string' ? result : JSON.stringify(result))
+                        }
+                        return result
+                    })
+
+                // Response closed by middleware
+                if(responseSent || s.writableEnded) return
+
+                // Try to serve public file
+                if(public_file(r, s)) {
+                    responseSent = true
+                    return
+                }
+
+                const url = rrurl.split('/')[1].split('?')[0]
+                if (routes[url]) {
+                    const resp = routes[url](r, s, data)
+                    if (!responseSent && !s.writableEnded) {
+                        responseSent = true
+                        s.end(typeof resp === 'string' ? resp:JSON.stringify(resp))
+                    }
+                    return
+                }
+                
+                if (!responseSent && !s.writableEnded) {
+                    responseSent = true
+                    s.writeHead(404);
+                    s.end();
+                }
+            } catch (e) {
+                console.error(e.stack)
+                if (!responseSent && !s.writableEnded) {
+                    responseSent = true
+                    s.writeHead(500).end()
+                }
+            }
+        })
+    }
+
+    let server
+    if (params.secure) {
+        const certPath = './cert.pem'
+        const keyPath = './key.pem'
+        
+        if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
+            throw new Error('Certificate files not found. Run ./generate-certs.sh first.')
+        }
+        
+        const options = {
+            cert: fs.readFileSync(certPath),
+            key: fs.readFileSync(keyPath)
+        }
+        
+        server = https.createServer(options, requestHandler)
+    } else {
+        server = http.createServer(requestHandler)
+    }
+
+    server.listen(port || 3000, ip || '')
+
+    const protocol = params.secure ? 'https' : 'http'
+    console.log(`started on: ${protocol}://${(process.env.ip || ip)}:${(process.env.port || port)}, public: ${publicDir}, ${Object.keys(routes).length > 0 ? `using routes: ${Object.keys(routes)}` : 'not using routes'}`)
+    
+    return {
+        routes: routes,
+        port: port,
+        server: server,
+        stop: () => { server.close(); return true }
+    }
+}

package/package.json

@@ -1,5 +1,14 @@
-{
-  "name": "instaserve",
-  "version": "1.0.21",
-  "bin": "./index.mjs"
-}
+{
+    "name": "instaserve",
+    "version": "1.1.2",
+    "description": "Instant web stack",
+    "main": "module.mjs",
+    "bin": "./instaserve",
+    "scripts": {
+        "start": "node instaserve"
+    },
+    "type": "module",
+    "dependencies": {
+        "chalk": "^5.6.2"
+    }
+}

package/routes_example.md

@@ -0,0 +1,54 @@
+/*
+ * This file defines the API routes and middleware for the Instaserve web server.
+ * 
+ * The file exports a default object containing route handlers and middleware functions.
+ * 
+ * Middleware functions (prefixed with _):
+ * - _debug: Logs request method, URL and data to console
+ * - _returnfalsy: Example middleware that returns true to stop request processing
+ * - _example: Demonstrates middleware behavior with console log
+ * - _end: Example of early response termination (commented out)
+ * 
+ * Route handlers:
+ * - api: Returns a string response with the request data
+ * - testerror: Throws an error for testing error handling
+ * - testdata: Example route that returns the context parameter
+ * 
+ * Each route handler receives:
+ * - req: HTTP request object
+ * - s: HTTP response object
+ * - data: Combined request data (POST body, query params, form data)
+ */
+
+export default {
+    // Middleware functions (prefixed with _) run on every request
+    // Return false to continue processing, or a value to use as response
+    
+    // Example: Log all requests
+    _log: (req, res, data) => {
+        console.log(`${req.method} ${req.url}`)
+        return false // Continue to next middleware or route
+    },
+
+    /**** Example: Basic authentication
+    _auth: (req, res, data) => {
+        if (!data.token) {
+            res.writeHead(401)
+            return 'Unauthorized'
+        }
+        return false // Continue if authorized
+    }, */
+
+    // Regular route handlers
+    hello: (req, res, data) => {
+        return { message: 'Hello World' }
+    },
+
+    _debug: ({method, url}, s, data) => { console.log(method, url, data) },
+    _example: (r, s) => console.log('in routes.mjs, returning a truthy value (above) will stop the chain'),
+    // _returnfalsy: (r, s) => { return true }, // Commented out - interferes with static file serving
+
+    api: (r, s, data) => 'an example api response, data:' + JSON.stringify(data),
+    testerror: () => { throw new Error('this from testerror') },
+    testdata: (r, s, c, d) => c
+}

package/index.mjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log(1)