Add circuit breaker plugin

Author: Camillarhi

docs/circuit-breaker.md

@@ -0,0 +1,156 @@
+# Circuit Breaker for Warnet
+
+## Overview
+
+Circuit Breaker is a Lightning Network firewall that protects LND nodes from being flooded with HTLCs. When integrated with Warnet, Circuit Breaker runs as a sidecar container alongside your LND nodes.
+
+Circuit Breaker is to Lightning what firewalls are to the internet - it allows nodes to protect themselves by setting maximum limits on in-flight HTLCs on a per-peer basis and applying rate limits to forwarded HTLCs.
+
+* **Repository**: https://github.com/lightningequipment/circuitbreaker
+* **Full Documentation**: See the main repository for detailed information about Circuit Breaker's features, operating modes, and configuration options
+
+## Usage in Warnet
+
+### Basic Configuration
+
+To enable Circuit Breaker for an LND node in your `network.yaml` file, add the `circuitbreaker` section under the `lnd` configuration:
+
+```yaml
+nodes:
+  - name: tank-0003
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+    lnd:
+      config: |
+        bitcoin.timelockdelta=33
+      channels:
+        - id:
+            block: 300
+            index: 1
+          target: tank-0004-ln
+          capacity: 100000
+          push_amt: 50000
+      circuitbreaker:
+        enabled: true    # This enables Circuit Breaker for this node
+        httpPort: 9235   # Can override default port per-node (optional)
+```
+
+### Configuration Options
+
+- `enabled`: Set to `true` to enable Circuit Breaker for the node
+- `httpPort`: Override the default HTTP port (9235) for the web UI (optional)
+
+### Complete Example
+
+Here's a complete `network.yaml` example with Circuit Breaker enabled on one node:
+
+```yaml
+nodes:
+  - name: tank-0000
+    addnode:
+      - tank-0001
+    ln:
+      lnd: true
+
+  - name: tank-0001
+    addnode:
+      - tank-0002
+    ln:
+      lnd: true
+
+  - name: tank-0002
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+
+  - name: tank-0003
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+    lnd:
+      config: |
+        bitcoin.timelockdelta=33
+      channels:
+        - id:
+            block: 300
+            index: 1
+          target: tank-0004-ln
+          capacity: 100000
+          push_amt: 50000
+      circuitbreaker:
+        enabled: true
+        httpPort: 9235
+
+  - name: tank-0004
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+    lnd:
+      channels:
+        - id:
+            block: 300
+            index: 2
+          target: tank-0005-ln
+          capacity: 50000
+          push_amt: 25000
+
+  - name: tank-0005
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+```
+
+## Accessing the Web UI
+
+Circuit Breaker provides a web-based interface for configuration and monitoring. To access it:
+
+1. **Port Forward to the Circuit Breaker service**:
+   ```bash
+   kubectl port-forward pod/<node-name>-ln <local-port>:<httpPort>
+   ```
+   
+   For example, if your node is named `tank-0003` and using the default port:
+   ```bash
+   kubectl port-forward pod/tank-0003-ln 9235:9235
+   ```
+
+2. **Open your browser** and navigate to:
+   ```
+   http://localhost:9235
+   ```
+
+3. **Configure your firewall rules** through the web interface:
+   - Set per-peer HTLC limits
+   - Configure rate limiting parameters
+   - Choose operating modes
+   - Monitor HTLC statistics
+
+## Architecture
+
+Circuit Breaker runs as a sidecar container alongside your LND node in Warnet:
+- **LND Container**: Runs your Lightning node
+- **Circuit Breaker Container**: Connects to LND via RPC and provides firewall functionality
+- **Shared Volume**: Allows Circuit Breaker to access LND's TLS certificates and macaroons
+- **Web Interface**: Accessible via port forwarding for configuration
+
+## Requirements
+
+- **LND Version**: 0.15.4-beta or above
+- **Warnet**: Compatible with standard Warnet LND deployments
+
+## Support
+
+For issues and questions:
+- Circuit Breaker Repository: https://github.com/lightningequipment/circuitbreaker
+- Warnet Documentation: Refer to the Warnet installation guides [install.md](install.md)
+- LND Documentation: https://docs.lightning.engineering/
+
+---
+
+*Circuit Breaker integration for Warnet enables sophisticated HTLC management and protection for Lightning Network nodes in test environments.*

resources/charts/bitcoincore/charts/lnd/templates/pod.yaml

@@ -58,16 +58,37 @@ spec:
         - mountPath: /root/.lnd/tls.cert
           name: config
           subPath: tls.cert
+        - name: shared-volume
+          mountPath: /root/.lnd/
     {{- with .Values.extraContainers }}
     {{- toYaml . | nindent 4 }}
     {{- end }}
+    {{- if .Values.circuitbreaker.enabled }}
+    - name: circuitbreaker
+      image: {{ .Values.circuitbreaker.image | quote }}
+      imagePullPolicy: IfNotPresent
+      args:
+        - "--network={{ .Values.global.chain }}"
+        - "--rpcserver=localhost:{{ .Values.RPCPort }}"
+        - "--tlscertpath=/tls.cert"
+        - "--macaroonpath=/root/.lnd/data/chain/bitcoin/{{ .Values.global.chain }}/admin.macaroon"
+        - "--httplisten=0.0.0.0:{{ .Values.circuitbreaker.httpPort }}"
+      volumeMounts:
+        - name: shared-volume
+          mountPath: /root/.lnd/
+        - name: config
+          mountPath: /tls.cert
+          subPath: tls.cert
+    {{- end }}
   volumes:
     {{- with .Values.volumes }}
       {{- toYaml . | nindent 4 }}
     {{- end }}
     - configMap:
         name: {{ include "lnd.fullname" . }}
       name: config
+    - name: shared-volume
+      emptyDir: {}
   {{- with .Values.nodeSelector }}
   nodeSelector:
     {{- toYaml . | nindent 4 }}

resources/charts/bitcoincore/charts/lnd/values.yaml

@@ -132,3 +132,8 @@ config: ""
 defaultConfig: ""
 
 channels: []
+
+circuitbreaker:
+  enabled: false  # Default to disabled
+  image: carlakirkcohen/circuitbreaker:attackathon-test
+  httpPort: 9235

test/data/ln/network.yaml

@@ -21,6 +21,10 @@ nodes:
           target: tank-0004-ln
           capacity: 100000
           push_amt: 50000
+      circuitbreaker:
+        enabled: true
+        httpPort: 9235
+
   - name: tank-0004
     addnode:
       - tank-0000

test/data/network_with_plugins/network.yaml

@@ -32,6 +32,9 @@ nodes:
           target: tank-0004-ln
           capacity: 100000
           push_amt: 50000
+      circuitbreaker:
+        enabled: true  # This enables circuitbreaker for this node
+        httpPort: 9235 # Can override defaults per-node
 
   - name: tank-0004
     addnode:
@@ -85,3 +88,4 @@ plugins:  # Each plugin section has a number of hooks available (preDeploy, post
       entrypoint: "../plugins/hello"
       helloTo: "postNetwork!"
       podName: "hello-post-network"
+      

test/ln_basic_test.py

@@ -2,12 +2,16 @@
 
 import json
 import os
+import random
+import subprocess
+import time
 from pathlib import Path
 from time import sleep
 
+import requests
 from test_base import TestBase
 
-from warnet.process import stream_command
+from warnet.process import run_command
 
 
 class LNBasicTest(TestBase):
@@ -24,11 +28,18 @@ def __init__(self):
             "tank-0005-ln",
         ]
 
+        self.cb_port = 9235
+        self.cb_node = "tank-0003-ln"
+        self.port_forward = None
+
     def run_test(self):
         try:
             # Wait for all nodes to wake up. ln_init will start automatically
             self.setup_network()
 
+            # Test circuit breaker API
+            self.test_circuit_breaker_api()
+
             # Send a payment across channels opened automatically by ln_init
             self.pay_invoice(sender="tank-0005-ln", recipient="tank-0003-ln")
 
@@ -39,11 +50,12 @@ def run_test(self):
             self.pay_invoice(sender="tank-0000-ln", recipient="tank-0002-ln")
 
         finally:
+            self.cleanup_kubectl_created_services()
             self.cleanup()
 
     def setup_network(self):
         self.log.info("Setting up network")
-        stream_command(f"warnet deploy {self.network_dir}")
+        run_command(f"warnet deploy {self.network_dir}")
 
     def fund_wallets(self):
         outputs = ""
@@ -120,6 +132,98 @@ def scenario_open_channels(self):
         self.log.info(f"Running scenario from: {scenario_file}")
         self.warnet(f"run {scenario_file} --source_dir={self.scen_dir} --debug")
 
+    def test_circuit_breaker_api(self):
+        self.log.info("Testing Circuit Breaker API")
+
+        # Set up port forwarding to the circuit breaker
+        cb_url = self.setup_api_access(self.cb_node)
+
+        self.log.info(f"Testing Circuit Breaker API at {cb_url}")
+
+        # Test /info endpoint
+        info = self.cb_api_request(cb_url, "get", "/info")
+        assert "version" in info, "Circuit breaker info missing version"
+
+        # Test /limits endpoint
+        limits = self.cb_api_request(cb_url, "get", "/limits")
+        assert isinstance(limits, dict), "Limits should be a dictionary"
+
+        self.log.info("✅ Circuit Breaker API tests passed")
+
+    def setup_api_access(self, pod_name):
+        """Set up Kubernetes Service access to the Circuit Breaker API"""
+        # Create a properly labeled service using kubectl expose
+        service_name = f"{pod_name}-svc"
+
+        self.log.info(f"Creating service {service_name} for pod {pod_name}")
+
+        command = f"kubectl expose pod {pod_name} --name {service_name} --port {self.cb_port} --target-port {self.cb_port}"
+        result = run_command(command)
+        self.log.info(f"Service creation command output: {result}")
+
+        time.sleep(51)  # Wait for the service to be created
+
+        service_url = f"http://{service_name}:{self.cb_port}/api"
+        self.service_to_cleanup = service_name
+        self.log.info(f"Service URL: {service_url}")
+
+        self.log.info(f"Successfully created service at {service_url}")
+        return service_url
+
+    def cb_api_request(self, base_url, method, endpoint, data=None):
+        """Universal API request handler with proper path handling"""
+        try:
+            # Parse the base URL components
+            url_parts = base_url.split("://")[1].split("/")
+            service_name = url_parts[0].split(":")[0]
+            port = url_parts[0].split(":")[1] if ":" in url_parts[0] else "80"
+            base_path = "/" + "/".join(url_parts[1:]) if len(url_parts) > 1 else "/"
+
+            # Set up port forwarding
+            local_port = random.randint(10000, 20000)
+            pf = subprocess.Popen(
+                ["kubectl", "port-forward", f"svc/{service_name}", f"{local_port}:{port}"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+
+            try:
+                # Wait for port-forward to establish
+                time.sleep(2)
+
+                # Construct the full local URL with proper path handling
+                full_path = base_path.rstrip("/") + "/" + endpoint.lstrip("/")
+                local_url = f"http://localhost:{local_port}{full_path}"
+
+                self.log.debug(f"Attempting API request to: {local_url}")
+
+                # Make the request
+                if method.lower() == "get":
+                    response = requests.get(local_url, timeout=30)
+                else:
+                    response = requests.post(local_url, json=data, timeout=30)
+
+                response.raise_for_status()
+                return response.json()
+
+            finally:
+                pf.terminate()
+                pf.wait()
+
+        except Exception as e:
+            self.log.error(f"API request to {local_url} failed: {str(e)}")
+            raise
+
+    def cleanup_kubectl_created_services(self):
+        """Clean up any created resources"""
+        if hasattr(self, "service_to_cleanup") and self.service_to_cleanup:
+            self.log.info(f"Deleting service {self.service_to_cleanup}")
+            subprocess.run(
+                ["kubectl", "delete", "svc", self.service_to_cleanup],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+
 
 if __name__ == "__main__":
     test = LNBasicTest()