@scemoon/cdh 1.0.7 → 1.0.9-beta.1

package/ai-dlc-skill/providers/tcb/services/cloud-functions.md

@@ -0,0 +1,265 @@
+# CloudBase Functions (FaaS)
+
+## When to Use CloudBase Functions
+
+**Use CloudBase Functions when:**
+- Responding to HTTP requests (API endpoints)
+- Processing events (timer triggers, queue messages, file uploads)
+- Running short-lived, stateless computations (< 60s)
+- Needing automatic scaling without managing servers
+
+**Do NOT use CloudBase Functions when:**
+- Execution time exceeds 60 seconds → Use CloudBase Run
+- Need persistent connections or background workers
+- Require GPU or large memory (> 1536MB)
+- Stateful computation requiring local disk persistence
+
+## Agent Decision Guide
+
+```
+Need serverless compute?
+├── Short task (<60s), event-driven → CloudBase Functions
+├── Long-running, persistent state → CloudBase Run
+└── Containerized workload → CloudBase Run (--deployMode image)
+```
+
+## Function Types
+
+### HTTP Functions
+
+Responding to HTTP requests. Deployed with `--httpFn` flag.
+
+```javascript
+// index.js
+exports.main = async (event, context) => {
+  // event: HTTP request (query, body, headers)
+  // context: TCB environment info
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ message: "Hello World" })
+  };
+};
+```
+
+**Access URL pattern:** `https://{env-id}.tcb-preview.com/{function-path}`
+
+### WebSocket Functions
+
+For real-time bidirectional communication. Use `--ws` flag.
+
+```javascript
+exports.main = async (event, context) => {
+  // event: { type: 'connect' | 'message' | 'disconnect', ... }
+  switch (event.type) {
+    case 'connect':
+      // Handle new connection
+      break;
+    case 'message':
+      // Handle incoming message
+      break;
+    case 'disconnect':
+      // Handle disconnection
+      break;
+  }
+};
+```
+
+### Background Functions
+
+Triggered by timers, COS events, or other triggers (not HTTP).
+
+```javascript
+// Cron-triggered function
+exports.main = async (event, context) => {
+  // event: { trigger: 'timer', ... }
+  // Run cleanup, send notifications, etc.
+};
+```
+
+## Function Structure
+
+```
+my-function/
+├── index.js          # Entry point (exports.main)
+├── package.json      # Dependencies
+├── cloudbaserc.json  # Function config
+└── node_modules/     # Dependencies (if local)
+```
+
+### cloudbaserc.json Example
+
+```json
+{
+  "functionRoot": "./functions",
+  "functions": [
+    {
+      "name": "hello",
+      "timeout": 10,
+      "memory": 256,
+      "handler": "index.main",
+      "runtime": "Nodejs16.13",
+      "triggers": [
+        {
+          "name": "myTrigger",
+          "type": "timer",
+          "config": "0 0 * * * *"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Deployment Options
+
+### Standard Deployment (COS mode, default)
+
+```bash
+tcb fn deploy --name hello --dir ./functions --env $TCB_ENV_ID
+```
+
+Files uploaded to COS bucket, extracted at runtime.
+
+### Zip Mode (≤1.5MB)
+
+```bash
+tcb fn deploy --name hello --dir ./functions --deployMode zip --env $TCB_ENV_ID
+```
+
+For small functions without many dependencies.
+
+### Image Mode (Container)
+
+```bash
+tcb fn deploy --name hello --deployMode image --env $TCB_ENV_ID
+```
+
+For complex dependencies or custom runtimes.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `tcb fn list --env <envId>` | List all functions |
+| `tcb fn deploy --name <name> --dir <path> --env <envId>` | Deploy function |
+| `tcb fn invoke --name <name> --params '{}' --env <envId>` | Invoke function |
+| `tcb fn logs --name <name> --env <envId>` | View function logs |
+| `tcb fn detail --name <name> --env <envId>` | Get function details |
+| `tcb fn delete --name <name> --env <envId>` | Delete function |
+| `tcb fn trigger --name <name> --trigger <trigger> --config <config>` | Create trigger |
+
+## Limits and Quotas
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Timeout | 60s (default), up to 60s | Use CloudBase Run for longer |
+| Memory | 128-1536MB | Adjust in cloudbaserc.json |
+| Max instances | 100 | Per function, auto-scaling |
+| Package size | 256MB (compressed) | Include dependencies |
+| Environment variables | 256KB total | Per function |
+| Concurrent executions | 1000 (default) | Can request increase |
+
+## Cold Start Optimization
+
+### Problem
+Cold start adds 100-500ms latency when function is idle.
+
+### Solutions
+
+1. **Keep function warm with timer trigger**
+```json
+{
+  "triggers": [
+    {
+      "name": "keep-warm",
+      "type": "timer",
+      "config": "*/5 * * * *"
+    }
+  ]
+}
+```
+
+2. **Reduce package size**
+- Minimize dependencies
+- Use ES modules
+- Tree-shake unused code
+
+3. **Use larger memory allocation**
+- More memory → faster CPU → faster cold start
+- 512MB+ recommended for latency-sensitive functions
+
+4. **Choose Node.js runtime**
+- Node.js cold start is faster than Python
+
+## Error Handling
+
+### Function Errors
+
+```javascript
+exports.main = async (event, context) => {
+  try {
+    // Business logic
+    const result = await processData(event);
+    return { success: true, data: result };
+  } catch (error) {
+    // Log error for debugging
+    console.error('Error:', error.message);
+    // Return error response
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: error.message })
+    };
+  }
+};
+```
+
+### Retry Behavior
+
+- HTTP functions: No automatic retry (client should retry)
+- Background functions: TCB handles retries based on trigger type
+- For critical operations, implement idempotency
+
+## Accessing TCB Services from Functions
+
+```javascript
+exports.main = async (event, context) => {
+  // Access via TCB environment variables
+  const envId = process.env.TCB_ENV_ID;
+  const secretId = process.env.TENCENTCLOUD_SECRETID;
+  const secretKey = process.env.TENCENTCLOUD_SECRETKEY;
+
+  // Or use TCB DB SDK
+  const tcb = require('@cloudbase/node-sdk');
+  const app = tcb.init({
+    env: envId,
+    credentials: { secretId, secretKey }
+  });
+  const db = app.database();
+
+  // Query database
+  const { data } = await db.collection('users').get();
+  return { users: data };
+};
+```
+
+## Best Practices
+
+1. **Stateless design** - Don't rely on in-memory state between invocations
+2. **Graceful shutdown** - Return response before cleanup
+3. **Idempotent operations** - Handle duplicate invocations gracefully
+4. **Structured logging** - Use `console.log` with JSON format
+5. **Environment-specific config** - Use env vars, not hardcoded values
+6. **Minimize dependencies** - Faster cold start, smaller package
+7. **Set appropriate timeout** - Not too short (failures), not too long (cost)
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Function timeout | Long execution | Optimize code or use CloudBase Run |
+| 403 Forbidden | Permission error | Check TCB env ID and credentials |
+| Cold start too slow | Large package | Minimize dependencies, use timer keep-warm |
+| Memory exceeded | Memory limit | Increase memory in cloudbaserc.json |
+| Concurrent limit reached | Too many requests | Request increase or implement throttling |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/services/cloud-hosting.md

@@ -0,0 +1,264 @@
+# CloudBase Hosting
+
+## When to Use CloudBase Hosting
+
+**Use CloudBase Hosting when:**
+- Deploy static websites (SPA, static sites)
+- Host mini-program webview content
+- Serve static assets with global CDN
+- Need automatic HTTPS and custom domains
+- Simple SSR (Server-Side Rendering) with Node.js
+
+**Do NOT use CloudBase Hosting when:**
+- Need server-side business logic → Use CloudBase Functions
+- Need real-time features → Use CloudBase Functions + WebSocket
+- Complex SSR framework → Consider CloudBase Run instead
+
+## Agent Decision Guide
+
+```
+Need to serve web content?
+├── Static site (HTML/CSS/JS) → CloudBase Hosting
+├── SPA with API backend → CloudBase Hosting + CloudBase Functions
+├── SSR with Node.js → CloudBase Hosting (Node SSR) or CloudBase Run
+└── Full web app with SSR → CloudBase Run (container)
+```
+
+## Hosting Features
+
+| Feature | Description |
+|---------|-------------|
+| Global CDN | 200+ edge nodes worldwide |
+| Automatic HTTPS | Free SSL certificates via Let's Encrypt |
+| Custom Domain | Bring your own domain |
+| SPA Routing | Rewrites all 404s to index.html |
+| Cache Control | Per-file cache headers |
+| CI/CD Integration | Auto-deploy on git push |
+
+## Deployment
+
+### Basic Deployment
+
+```bash
+tcb hosting deploy --env $TCB_ENV_ID --dir ./dist
+```
+
+### With Build Environment Variables
+
+```bash
+tcb hosting deploy \
+  --env $TCB_ENV_ID \
+  --dir ./dist \
+  --build-env BACKEND_URL=https://api.example.com
+```
+
+### With Configuration File (cloudbaserc.json)
+
+```json
+{
+  "hosting": {
+    "dev": {
+      "cloudPath": "./dist",
+      "envId": "env-xxxxx"
+    },
+    "release": {
+      "cloudPath": "./dist",
+      "envId": "env-prod"
+    }
+  }
+}
+```
+
+```bash
+tcb hosting deploy --env release
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `tcb hosting deploy --env <envId> --dir <path>` | Deploy static site |
+| `tcb hosting list --env <envId>` | List hosting projects |
+| `tcb hosting detail --env <envId>` | Get hosting details |
+| `tcb hosting delete --env <envId>` | Delete hosting project |
+| `tcb hosting domain add --domain <domain> --env <envId>` | Add custom domain |
+
+## URL Structure
+
+| Environment | URL Pattern |
+|-------------|-------------|
+| Preview | `https://{env-id}-{project}.tcb-preview.com` |
+| Staging | `https://{env-id}.tcb-preview.com` |
+| Production | `https://{custom-domain}` or `https://{env-id}.tcb-ext.com` |
+
+## SPA Configuration
+
+### How SPA Routing Works
+
+For Single Page Applications (Vue, React, Angular):
+
+1. All requests to non-file paths are rewritten to `index.html`
+2. Client-side router handles path rendering
+3. Direct links and refresh work correctly
+
+```
+Request: /user/profile
+  ↓ Not a file, not /index.html
+  ↓ Rewrite to /index.html
+  ↓ Frontend router handles /user/profile
+```
+
+### Configuration (if needed)
+
+Usually automatic, but can configure in `cloudbaserc.json`:
+
+```json
+{
+  "hosting": {
+    "dev": {
+      "cloudPath": "./dist",
+      "ignore": ["*.map"],
+      "router": {
+        "enable": true,
+        "rewrites": [
+          { "regxp": "^/api", "target": "https://api.example.com" }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Cache Configuration
+
+### Default Cache Behavior
+
+| File Type | Cache Duration |
+|-----------|----------------|
+| HTML | No cache (always fresh) |
+| JS/CSS | 1 year (immutable) |
+| Images | 1 week |
+| Other | 1 day |
+
+### Cache Headers
+
+Set custom cache in `cloudbaserc.json`:
+
+```json
+{
+  "hosting": {
+    "dev": {
+      "cloudPath": "./dist",
+      "headers": [
+        {
+          "path": "*.json",
+          "headers": {
+            "Cache-Control": "no-cache"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Environment Injection
+
+Inject environment-specific values at build time:
+
+```bash
+# Deploy with build environment
+tcb hosting deploy --env $TCB_ENV_ID --dir ./dist --build-env API_URL=$API_URL
+```
+
+This makes variables available during the build process (Vite, Webpack, etc.).
+
+### Build Time vs Runtime
+
+| Type | Available | Use Case |
+|------|-----------|----------|
+| `--build-env` | At build time | `process.env.API_URL` in webpack/vite |
+| Runtime env | In browser | Public config loaded from API |
+
+## Custom Domain
+
+### Add Custom Domain
+
+```bash
+# Step 1: Add domain
+tcb hosting domain add --domain example.com --env $TCB_ENV_ID
+
+# Step 2: Add DNS record (shown after domain add)
+# Type: CNAME
+# Value: {env-id}.tcb-ext.com
+
+# Step 3: Wait for SSL certificate (automatic)
+```
+
+### SSL Certificate
+
+- Automatic issuance via Let's Encrypt
+- Renewal before expiration
+- Supports wildcard certificates
+
+## Integration with Backend
+
+### Pattern: Frontend + API Functions
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Browser                                  │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │  Frontend App (CloudBase Hosting)                     │  │
+│   │  - Loads config from window.__ENV__                  │  │
+│   │  - Calls API via BACKEND_URL                         │  │
+│   └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              CloudBase Functions (Backend API)               │
+│   - /api/users → getUsers()                                 │
+│   - /api/orders → createOrder()                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   CloudBase Database                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Build with Backend URL
+
+```bash
+# Deploy web with BACKEND_URL injected
+tcb hosting deploy \
+  --env $TCB_ENV_ID \
+  --dir ./dist \
+  --build-env BACKEND_URL=$STACK_URL
+
+# In frontend code
+const API_BASE = process.env.BACKEND_URL || 'http://localhost:3000';
+```
+
+## Best Practices
+
+1. **Use build tools** - Don't deploy raw HTML, use Vite/Webpack
+2. **Enable gzip/brotli** - Configure in build tool for smaller assets
+3. **Use immutable hashes** - Filename hashes for cache busting
+4. **Optimize images** - Compress images, use WebP format
+5. **Set long cache for assets** - JS/CSS with content hash
+6. **SPA routing** - Ensure all routes serve index.html
+7. **Environment separation** - Different env IDs for dev/staging/prod
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| 404 on refresh (SPA) | Routing not configured | CloudBase handles this automatically |
+| Stale content | Cache not cleared | Deploy with `--force` or new path |
+| Slow first load | Large bundle | Code split, lazy load routes |
+| CORS errors | API not allowing origin | Configure CORS in function |
+| Mixed content | HTTP assets on HTTPS page | Use HTTPS for all resources |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`