openkbs 0.0.64 → 0.0.65

package/elastic/functions.md

@@ -0,0 +1,328 @@
+# Tutorial 13: Serverless Functions
+
+Deploy serverless APIs with AWS Lambda. Write your code in Node.js, Python, or Java. Get HTTPS endpoints automatically.
+
+## Create a Function
+
+### Project Structure
+
+```
+my-app/
+├── openkbs.json
+├── functions/
+│   └── api/
+│       ├── index.mjs      # Node.js handler
+│       └── package.json   # Dependencies
+└── site/
+    └── index.html
+```
+
+### Node.js Function
+
+Create `functions/api/index.mjs`:
+
+```javascript
+export async function handler(event) {
+    const { action, ...data } = JSON.parse(event.body || '{}');
+
+    switch (action) {
+        case 'hello':
+            return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ message: `Hello, ${data.name || 'World'}!` })
+            };
+
+        case 'echo':
+            return {
+                statusCode: 200,
+                body: JSON.stringify({ received: data })
+            };
+
+        default:
+            return {
+                statusCode: 400,
+                body: JSON.stringify({ error: 'Unknown action' })
+            };
+    }
+}
+```
+
+Create `functions/api/package.json`:
+
+```json
+{
+  "type": "module",
+  "dependencies": {}
+}
+```
+
+### Python Function
+
+Create `functions/api/handler.py`:
+
+```python
+import json
+
+def handler(event, context):
+    body = json.loads(event.get('body', '{}'))
+    action = body.get('action')
+
+    if action == 'hello':
+        name = body.get('name', 'World')
+        return {
+            'statusCode': 200,
+            'body': json.dumps({'message': f'Hello, {name}!'})
+        }
+
+    return {
+        'statusCode': 400,
+        'body': json.dumps({'error': 'Unknown action'})
+    }
+```
+
+Create `functions/api/requirements.txt`:
+
+```
+# Add Python dependencies here
+```
+
+### Java Function
+
+Create `functions/api/src/main/java/com/example/Handler.java`:
+
+```java
+package com.example;
+
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+import com.google.gson.Gson;
+import java.util.Map;
+
+public class Handler implements RequestHandler<Map<String, Object>, Map<String, Object>> {
+    private static final Gson gson = new Gson();
+
+    @Override
+    public Map<String, Object> handleRequest(Map<String, Object> event, Context context) {
+        String body = (String) event.get("body");
+        Map<String, Object> request = gson.fromJson(body, Map.class);
+        String action = (String) request.get("action");
+
+        if ("hello".equals(action)) {
+            String name = (String) request.getOrDefault("name", "World");
+            return Map.of(
+                "statusCode", 200,
+                "body", gson.toJson(Map.of("message", "Hello, " + name + "!"))
+            );
+        }
+
+        return Map.of("statusCode", 400, "body", "{\"error\":\"Unknown action\"}");
+    }
+}
+```
+
+## Deploy
+
+```bash
+# Install dependencies
+cd functions/api && npm install && cd ../..
+
+# Deploy function
+openkbs fn push api
+```
+
+Your function is live at `https://your-kb.openkbs.com/api`.
+
+## Test Your Function
+
+### From CLI
+
+```bash
+openkbs fn invoke api '{"action":"hello","name":"OpenKBS"}'
+```
+
+### From Browser
+
+```javascript
+const response = await fetch('/api', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'hello', name: 'OpenKBS' })
+});
+
+const data = await response.json();
+console.log(data); // { message: "Hello, OpenKBS!" }
+```
+
+### With curl
+
+```bash
+curl -X POST https://your-kb.openkbs.com/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"hello","name":"OpenKBS"}'
+```
+
+## Environment Variables
+
+Elastic services inject these automatically:
+
+| Variable | Description |
+|----------|-------------|
+| `OPENKBS_KB_ID` | Your KB ID |
+| `OPENKBS_API_KEY` | API key |
+| `DATABASE_URL` | PostgreSQL connection (if enabled) |
+| `STORAGE_BUCKET` | S3 bucket name (if enabled) |
+| `STORAGE_REGION` | S3 region (if enabled) |
+
+### View Environment
+
+```bash
+openkbs fn env api
+```
+
+### Set Custom Variables
+
+```bash
+openkbs fn env api STRIPE_KEY=sk_live_xxx
+openkbs fn env api DEBUG=true
+```
+
+### Remove Variable
+
+```bash
+openkbs fn env api STRIPE_KEY=
+```
+
+## Configure Memory & Timeout
+
+```bash
+# Default: 128MB memory, 30s timeout
+openkbs fn push api
+
+# More memory (= more CPU)
+openkbs fn push api --memory 512
+
+# Longer timeout (max 900s)
+openkbs fn push api --timeout 60
+
+# Both
+openkbs fn push api --memory 1024 --timeout 120
+```
+
+Memory options: 128, 256, 512, 1024, 2048, 3008 MB
+
+## View Logs
+
+```bash
+openkbs fn logs api
+openkbs fn logs api --limit 100
+openkbs fn logs api --follow  # Stream logs
+```
+
+## CORS Headers
+
+For browser access, add CORS headers:
+
+```javascript
+export async function handler(event) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Content-Type'
+    };
+
+    // Handle OPTIONS preflight
+    if (event.requestContext?.http?.method === 'OPTIONS') {
+        return { statusCode: 200, headers, body: '' };
+    }
+
+    // Your logic here...
+
+    return { statusCode: 200, headers, body: JSON.stringify({ success: true }) };
+}
+```
+
+## Multiple Functions
+
+```
+functions/
+├── auth/
+│   ├── index.mjs
+│   └── package.json
+├── posts/
+│   ├── index.mjs
+│   └── package.json
+└── payments/
+    ├── index.mjs
+    └── package.json
+```
+
+`openkbs.json`:
+```json
+{
+  "name": "my-app",
+  "elastic": { "postgres": true },
+  "functions": ["auth", "posts", "payments"]
+}
+```
+
+Deploy all at once:
+```bash
+openkbs deploy
+```
+
+Or individually:
+```bash
+openkbs fn push auth
+openkbs fn push posts
+```
+
+## List Functions
+
+```bash
+openkbs fn list
+```
+
+Output:
+```
+Functions:
+  api      128MB  30s  https://your-kb.openkbs.com/api
+  auth     256MB  30s  https://your-kb.openkbs.com/auth
+  posts    512MB  60s  https://your-kb.openkbs.com/posts
+```
+
+## Delete Function
+
+```bash
+openkbs fn delete api
+```
+
+## CLI Reference
+
+```bash
+openkbs fn list                      # List functions
+openkbs fn push <name>               # Deploy function
+openkbs fn push <name> --memory 512  # With memory
+openkbs fn push <name> --timeout 60  # With timeout
+openkbs fn logs <name>               # View logs
+openkbs fn logs <name> --follow      # Stream logs
+openkbs fn env <name>                # View env vars
+openkbs fn env <name> KEY=value      # Set env var
+openkbs fn invoke <name> '{}'        # Test invoke
+openkbs fn delete <name>             # Delete function
+```
+
+## Tips
+
+1. **Connection Reuse** - Initialize DB connections outside the handler for reuse.
+
+2. **Cold Starts** - More memory = faster cold starts. 512MB is a good default.
+
+3. **Timeout** - Set appropriate timeouts. Don't leave at 30s if your function takes 5s.
+
+4. **Logs** - Use `console.log()` (Node.js), `print()` (Python), or `context.getLogger()` (Java).
+
+## Next Steps
+
+- [Tutorial 14: Real-time Pulse](./14-pulse.md)
+- [Tutorial 15: Node.js Full Example](./15-nodejs-example.md)

package/elastic/postgres.md

@@ -0,0 +1,287 @@
+# Tutorial 11: PostgreSQL Database
+
+Add a PostgreSQL database to your project with one command. Elastic Postgres uses Neon - a serverless PostgreSQL that scales automatically.
+
+## Enable Postgres
+
+```bash
+openkbs postgres enable
+```
+
+That's it. Your database is ready.
+
+## Check Status
+
+```bash
+openkbs postgres status
+```
+
+Output:
+```
+Postgres Status:
+  Enabled: true
+  Host: ep-xyz-123456.us-east-1.aws.neon.tech
+  Database: neondb
+  Region: us-east-1
+```
+
+## Get Connection String
+
+```bash
+openkbs postgres connection
+```
+
+Output:
+```
+postgresql://user:password@ep-xyz-123456.us-east-1.aws.neon.tech/neondb?sslmode=require
+```
+
+## Use in Your Function
+
+The `DATABASE_URL` environment variable is automatically injected into your Lambda functions.
+
+### Node.js
+
+```javascript
+import pg from 'pg';
+
+const db = new pg.Client({ connectionString: process.env.DATABASE_URL });
+let connected = false;
+
+export async function handler(event) {
+    // Connect once, reuse across invocations
+    if (!connected) {
+        await db.connect();
+        connected = true;
+
+        // Create tables on first run
+        await db.query(`
+            CREATE TABLE IF NOT EXISTS users (
+                id SERIAL PRIMARY KEY,
+                name TEXT NOT NULL,
+                email TEXT UNIQUE NOT NULL,
+                created_at TIMESTAMP DEFAULT NOW()
+            )
+        `);
+    }
+
+    const { action, ...data } = JSON.parse(event.body || '{}');
+
+    switch (action) {
+        case 'list':
+            const { rows } = await db.query('SELECT * FROM users ORDER BY created_at DESC');
+            return { statusCode: 200, body: JSON.stringify(rows) };
+
+        case 'create':
+            const result = await db.query(
+                'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
+                [data.name, data.email]
+            );
+            return { statusCode: 200, body: JSON.stringify(result.rows[0]) };
+
+        case 'delete':
+            await db.query('DELETE FROM users WHERE id = $1', [data.id]);
+            return { statusCode: 200, body: JSON.stringify({ deleted: true }) };
+
+        default:
+            return { statusCode: 400, body: JSON.stringify({ error: 'Unknown action' }) };
+    }
+}
+```
+
+`package.json`:
+```json
+{
+  "type": "module",
+  "dependencies": {
+    "pg": "^8.11.3"
+  }
+}
+```
+
+### Python
+
+```python
+import json
+import os
+import psycopg2
+
+conn = None
+
+def handler(event, context):
+    global conn
+    if conn is None:
+        conn = psycopg2.connect(os.environ['DATABASE_URL'])
+        with conn.cursor() as cur:
+            cur.execute('''
+                CREATE TABLE IF NOT EXISTS items (
+                    id SERIAL PRIMARY KEY,
+                    name TEXT NOT NULL
+                )
+            ''')
+            conn.commit()
+
+    body = json.loads(event.get('body', '{}'))
+    action = body.get('action')
+
+    with conn.cursor() as cur:
+        if action == 'list':
+            cur.execute('SELECT * FROM items')
+            rows = cur.fetchall()
+            return {'statusCode': 200, 'body': json.dumps(rows)}
+
+        elif action == 'create':
+            cur.execute('INSERT INTO items (name) VALUES (%s) RETURNING id', (body['name'],))
+            conn.commit()
+            return {'statusCode': 200, 'body': json.dumps({'id': cur.fetchone()[0]})}
+
+    return {'statusCode': 400, 'body': json.dumps({'error': 'Unknown action'})}
+```
+
+### Java
+
+```java
+package com.example;
+
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+import com.google.gson.Gson;
+import java.sql.*;
+import java.util.*;
+
+public class Handler implements RequestHandler<Map<String, Object>, Map<String, Object>> {
+    private static Connection conn;
+    private static final Gson gson = new Gson();
+
+    @Override
+    public Map<String, Object> handleRequest(Map<String, Object> event, Context context) {
+        try {
+            if (conn == null || conn.isClosed()) {
+                conn = DriverManager.getConnection(System.getenv("DATABASE_URL"));
+                try (Statement stmt = conn.createStatement()) {
+                    stmt.execute("CREATE TABLE IF NOT EXISTS items (id SERIAL PRIMARY KEY, name TEXT)");
+                }
+            }
+
+            String body = (String) event.get("body");
+            Map<String, Object> request = gson.fromJson(body, Map.class);
+            String action = (String) request.get("action");
+
+            if ("list".equals(action)) {
+                List<Map<String, Object>> items = new ArrayList<>();
+                try (ResultSet rs = conn.createStatement().executeQuery("SELECT * FROM items")) {
+                    while (rs.next()) {
+                        items.add(Map.of("id", rs.getInt("id"), "name", rs.getString("name")));
+                    }
+                }
+                return Map.of("statusCode", 200, "body", gson.toJson(items));
+            }
+
+            return Map.of("statusCode", 400, "body", "{\"error\":\"Unknown action\"}");
+        } catch (Exception e) {
+            return Map.of("statusCode", 500, "body", "{\"error\":\"" + e.getMessage() + "\"}");
+        }
+    }
+}
+```
+
+## Common Patterns
+
+### Parameterized Queries (Prevent SQL Injection)
+
+```javascript
+// GOOD - parameterized
+await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+
+// BAD - string concatenation
+await db.query(`SELECT * FROM users WHERE id = ${userId}`); // NEVER DO THIS
+```
+
+### Pagination
+
+```javascript
+const page = data.page || 1;
+const limit = data.limit || 20;
+const offset = (page - 1) * limit;
+
+const { rows } = await db.query(
+    'SELECT * FROM items ORDER BY created_at DESC LIMIT $1 OFFSET $2',
+    [limit, offset]
+);
+
+const { rows: [{ count }] } = await db.query('SELECT COUNT(*) FROM items');
+
+return { items: rows, total: parseInt(count), page, limit };
+```
+
+### Search
+
+```javascript
+const { rows } = await db.query(
+    'SELECT * FROM items WHERE name ILIKE $1',
+    [`%${data.query}%`]
+);
+```
+
+### JSON Columns
+
+```javascript
+// Create table with JSONB column
+await db.query(`
+    CREATE TABLE IF NOT EXISTS products (
+        id SERIAL PRIMARY KEY,
+        name TEXT,
+        metadata JSONB DEFAULT '{}'
+    )
+`);
+
+// Query JSON
+const { rows } = await db.query(
+    "SELECT * FROM products WHERE metadata->>'category' = $1",
+    ['electronics']
+);
+
+// Update JSON field
+await db.query(
+    "UPDATE products SET metadata = jsonb_set(metadata, '{stock}', $1) WHERE id = $2",
+    [JSON.stringify(100), productId]
+);
+```
+
+### Transactions
+
+```javascript
+try {
+    await db.query('BEGIN');
+    await db.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [amount, fromId]);
+    await db.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [amount, toId]);
+    await db.query('COMMIT');
+} catch (e) {
+    await db.query('ROLLBACK');
+    throw e;
+}
+```
+
+## CLI Reference
+
+```bash
+openkbs postgres enable              # Enable database
+openkbs postgres status              # Check status
+openkbs postgres connection          # Get connection string
+openkbs postgres disable             # Disable (WARNING: deletes data)
+```
+
+## Tips
+
+1. **Connection Reuse** - Keep `db.connect()` outside the handler. Lambda reuses the connection across invocations.
+
+2. **Cold Starts** - Neon is serverless. First connection after idle may take 1-2 seconds.
+
+3. **Create Tables on Init** - Use `CREATE TABLE IF NOT EXISTS` in your connection logic.
+
+4. **Always Use Parameters** - Never concatenate user input into SQL strings.
+
+## Next Steps
+
+- [Tutorial 12: S3 Storage](./12-storage.md)
+- [Tutorial 13: Serverless Functions](./13-functions.md)