codeaura-embedded-runtime-agent 0.1.0

package/code_aura_embedded_runtime_agent_v_1_implementation_guide.md

@@ -0,0 +1,253 @@
+# CodeAura Embedded Runtime Agent – V1 Implementation Guide
+
+This document describes **how to implement Version 1 (V1)** of the CodeAura Embedded Runtime Agent.
+
+The goal of V1 is **not completeness**, but to deliver a **working, stable, and understandable foundation** that proves the concept and can evolve safely.
+
+---
+
+## 1. Scope of V1
+
+### What V1 MUST do
+
+- Run inside a **Sails.js (Node.js) application**
+- Capture runtime execution of:
+  - Controllers
+  - Helpers
+- Measure:
+  - Execution start / end
+  - Duration
+  - Errors (if any)
+- Emit structured execution events
+- Send events to the CodeAura API via HTTP
+
+### What V1 MUST NOT do
+
+- Support multiple frameworks
+- Support multiple languages
+- Persist data to disk
+- Implement complex retry or resilience logic
+- Capture database internals
+- Behave like a full APM solution
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Runtime Instrumentation
+
+The agent **does not analyze source code statically**.
+Instead, it instruments the application **at runtime** by wrapping functions while the application is starting.
+
+This ensures:
+- No breakpoints
+- No debugger
+- Real execution paths
+
+---
+
+### 2.2 Function Wrapping (Key Mechanism)
+
+The core mechanism of V1 is **function wrapping**:
+
+1. Take an existing function
+2. Replace it with a wrapper function
+3. Measure execution
+4. Capture metadata
+5. Call the original function
+
+This is applied to:
+- Sails controllers
+- Sails helpers
+
+---
+
+## 3. Step-by-Step Implementation Plan
+
+### Step 1 — Agent Entry Point (`Agent.js`)
+
+Responsibilities:
+- Load configuration
+- Initialize core services (buffer, transport)
+- Detect runtime environment
+- Initialize framework hooks
+
+Pseudo-flow:
+
+1. Agent.init(sails)
+2. Validate config
+3. Initialize EventBuffer
+4. Initialize HttpTransport
+5. Register Sails hook
+
+---
+
+### Step 2 — Sails Hook (`sailsHook.js`)
+
+Responsibilities:
+- Hook into the Sails lifecycle
+- Run once the app is loaded
+- Access controllers and helpers
+
+Key lifecycle point:
+- `sails.on('lifted')`
+
+At this stage:
+- Controllers and helpers are fully registered
+- Safe to wrap functions
+
+---
+
+### Step 3 — Controller Instrumentation
+
+Process:
+
+1. Iterate over `sails.controllers`
+2. For each controller action:
+   - Replace function with wrapped version
+3. Wrapper logic:
+   - Record start time
+   - Execute original action
+   - Catch errors
+   - Record end time
+   - Emit event
+
+Captured data:
+- controller name
+- action name
+- duration
+- HTTP metadata (method, route, status)
+
+---
+
+### Step 4 — Helper Instrumentation
+
+Process:
+
+1. Iterate over `sails.helpers`
+2. Wrap helper functions
+3. Track:
+   - helper name
+   - duration
+   - errors
+
+Important:
+- Helpers may be async or sync
+- Wrapper must support both
+
+---
+
+### Step 5 — Event Creation (`EventSchema.js`)
+
+Each execution produces an event:
+
+Required fields:
+- id
+- timestamp
+- type (controller | helper)
+- name
+- durationMs
+- framework
+- language
+
+Optional:
+- error
+- HTTP metadata
+
+---
+
+### Step 6 — Event Buffer (`memoryBuffer.js`)
+
+Responsibilities:
+- Temporarily store events in memory
+- Prevent sending one HTTP request per event
+
+Rules:
+- Simple array-based buffer
+- Flush when:
+  - buffer size reaches threshold
+  - timer interval expires
+
+---
+
+### Step 7 — Transport (`httpTransport.js`)
+
+Responsibilities:
+- Send batched events to CodeAura API
+
+Constraints:
+- Best-effort delivery
+- No retries in V1
+- Fail silently (log errors)
+
+---
+
+## 4. Configuration Strategy
+
+Minimal configuration:
+
+```js
+{
+  enabled: true,
+  endpoint: "https://api.codeaura.dev/events",
+  apiKey: "YOUR_API_KEY"
+}
+```
+
+Configuration should:
+- Be optional
+- Have safe defaults
+
+---
+
+## 5. Error Handling Philosophy (V1)
+
+Rule #1: **The agent must never crash the host application**.
+
+Therefore:
+- All agent code must be wrapped in try/catch
+- Errors are logged, not thrown
+- Instrumentation failure should disable itself gracefully
+
+---
+
+## 6. Testing Strategy (V1)
+
+### Manual testing
+
+- Create a sample Sails app
+- Install the agent
+- Trigger controller routes
+- Observe event logs
+
+### Success criteria
+
+- App runs normally
+- Events are emitted
+- No visible behavior change
+
+---
+
+## 7. What Comes Next (V2+)
+
+Once V1 is stable:
+
+- Add Express adapter
+- Introduce persistent buffering
+- Add retry strategies
+- Add data masking
+- Add execution context correlation
+- Introduce Python agent
+
+---
+
+## 8. Definition of Done (V1)
+
+V1 is complete when:
+
+- Agent can be installed via npm
+- Sails controllers & helpers are traced
+- Events reach CodeAura
+- Code is readable and maintainable
+- Architecture is ready for extension
+

package/index.js

@@ -0,0 +1,2 @@
+
+module.exports = require("./src/agent/Agent");

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "codeaura-embedded-runtime-agent",
+  "version": "0.1.0",
+  "description": "Lightweight runtime execution tracer for JavaScript applications",
+  "main": "index.js",
+  "keywords": [
+    "runtime",
+    "tracing",
+    "instrumentation",
+    "sailsjs",
+    "observability",
+    "codeaura"
+  ],
+  "author": "CodeAura",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "scripts": {
+    "test": "npm run lint && npm run custom-tests && echo 'Done.'",
+    "lint": "./node_modules/eslint/bin/eslint.js . --max-warnings=0 --report-unused-disable-directives",
+    "lint-windows": "eslint . --max-warnings=0 --report-unused-disable-directives -c .eslintrc --ignore-path .eslintignore",
+    "custom-tests": "echo \"(No other custom tests yet.)\" && echo"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.6",
+    "babel-eslint": "^10.1.0",
+    "eslint": "^8.55.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codeaura/codeaura-embedded-runtime-agent"
+  }
+}

package/src/agent/Agent.js

@@ -0,0 +1,224 @@
+
+const path = require("path"),
+    fs = require("fs"),
+    Config = require("../config/config"),
+    loggerModule = require("../utils/logger"),
+    MemoryBuffer = require("../core/buffer/memoryBuffer"),
+    HttpTransport = require("../core/transport/httpTransport");
+
+let agentInstance = null;
+
+class Agent {
+
+    constructor() {
+        this.config = null;
+        this.logger = null;
+        this.initialized = false;
+        this.buffer = null;
+        this.transport = null;
+        this.frameworkAdapter = null;
+    }
+
+    readProjectConfig() {
+        let configPath = null,
+            rawContent = null,
+            projectConfig = null;
+
+        try {
+            configPath = path.join(process.cwd(), "codeaura-config.json");
+            rawContent = fs.readFileSync(configPath, "utf8");
+            projectConfig = JSON.parse(rawContent);
+
+            return projectConfig;
+        } catch (unusedE) {
+            console.log("[CodeAura Agent] codeaura-config.json not found or invalid at: " + path.join(process.cwd(), "codeaura-config.json"));
+
+            return {};
+        }
+    }
+
+    init(userConfig = {}) {
+        let projectConfig = null;
+
+        try {
+            projectConfig = this.readProjectConfig();
+
+            if (projectConfig && projectConfig.project) {
+                userConfig.projectId = projectConfig.project;
+            }
+
+            this.config = new Config(userConfig);
+
+            this.logger = loggerModule.getLogger(this.config.get("logging"));
+
+            if (this.config.isEnabled()) {
+                this.logger.info("Initializing CodeAura Runtime Agent...");
+                this.logger.info("Project ID: " + (this.config.get("projectId") || "none"));
+
+                this.initializeCoreServices();
+                this.initializeFrameworkAdapter();
+
+                this.initialized = true;
+                this.logger.info("CodeAura Runtime Agent initialized successfully");
+            }
+        } catch (error) {
+            if (this.logger) {
+                this.logger.errorWithStack("Failed to initialize agent", error);
+            } else {
+                console.error("Failed to initialize agent", error);
+            }
+
+            throw error;
+        }
+    }
+
+    initializeCoreServices() {
+        try {
+            const transportConfig = this.config.get("transport"),
+                bufferConfig = this.config.get("buffer"),
+                agentConfig = this.config.getAll();
+
+            this.transport = new HttpTransport(transportConfig, agentConfig, this.logger);
+            this.buffer = new MemoryBuffer(bufferConfig, this.transport, this.logger, agentConfig);
+
+            this.logger.debug("Core services initialized successfully");
+        } catch (error) {
+            this.logger.errorWithStack("Failed to initialize core services", error);
+
+            throw error;
+        }
+    }
+
+    initializeFrameworkAdapter() {
+        try {
+            const frameworkConfig = this.config.get("framework");
+
+            let AdapterClass = null;
+
+            if (!frameworkConfig || typeof frameworkConfig !== "object" || !frameworkConfig.type) {
+                this.logger.info("No framework adapter configured, running in standalone mode");
+
+                return;
+            }
+
+            if (typeof frameworkConfig.type !== "string") {
+                throw new Error("Invalid framework configuration: 'type' must be a string");
+            }
+
+            this.logger.debug("Loading framework adapter for: " + frameworkConfig.type);
+
+            AdapterClass = this.loadFrameworkAdapter(frameworkConfig.type);
+
+            this.frameworkAdapter = new AdapterClass(frameworkConfig, this);
+            if (typeof this.frameworkAdapter.init === "function") {
+                this.frameworkAdapter.init();
+            }
+
+            this.logger.debug("Framework adapter initialized successfully");
+        } catch (error) {
+            this.logger.errorWithStack("Failed to initialize framework adapter", error);
+
+            throw error;
+        }
+    }
+
+    loadFrameworkAdapter(frameworkType) {
+        try {
+            let adapterPath;
+
+            switch (frameworkType.toLowerCase()) {
+                case "sails":
+                    adapterPath = path.resolve(__dirname, "../framework/nodejs/sails/SailsAdapter");
+                    break;
+                default:
+                    throw new Error(`Unsupported framework type: ${frameworkType}`);
+            }
+
+            const AdapterClass = require(adapterPath);
+
+            return AdapterClass;
+        } catch (error) {
+            this.logger.errorWithStack(`Failed to load framework adapter: ${frameworkType}`, error);
+
+            throw error;
+        }
+    }
+
+    getConfig() {
+        return this.config;
+    }
+
+    getLogger() {
+        return this.logger;
+    }
+
+    isInitialized() {
+        return this.initialized;
+    }
+
+    shutdown() {
+        try {
+            if (this.initialized) {
+                if (this.buffer) {
+                    this.buffer.shutdown();
+                }
+
+                if (this.frameworkAdapter && typeof this.frameworkAdapter.shutdown === "function") {
+                    this.frameworkAdapter.shutdown();
+                }
+
+                this.initialized = false;
+                this.logger.info("Agent shutdown complete");
+            }
+        } catch (error) {
+            this.logger.errorWithStack("Error during agent shutdown", error);
+        }
+    }
+}
+
+function init(sailsInstanceOrConfig, userConfig) {
+    if (!agentInstance) {
+        agentInstance = new Agent();
+    }
+
+    let finalConfig = {};
+
+    const isObject = (obj) => obj && typeof obj === "object" && !Array.isArray(obj),
+
+        isSailsInstance = isObject(sailsInstanceOrConfig) &&
+        sailsInstanceOrConfig.constructor &&
+        typeof sailsInstanceOrConfig.lift === "function" &&
+        typeof sailsInstanceOrConfig.hooks === "object";
+
+    if (isSailsInstance && isObject(userConfig)) {
+        finalConfig = userConfig;
+        finalConfig.framework = {
+            type: "sails",
+            instance: sailsInstanceOrConfig
+        };
+    } else if (!isSailsInstance && isObject(sailsInstanceOrConfig)) {
+        finalConfig = sailsInstanceOrConfig;
+    } else {
+        throw new Error("Invalid arguments: provide either (sailsInstance, config) or (config)");
+    }
+
+    agentInstance.init(finalConfig);
+
+    return agentInstance;
+}
+
+function getInstance() {
+    return agentInstance;
+}
+
+function shutdown() {
+    if (agentInstance) {
+        agentInstance.shutdown();
+    }
+}
+
+module.exports = {
+    init,
+    getInstance,
+    shutdown
+};