Merge branch 'main' into fix/dead-connections-with-subscriptions

Author: cameri

.eslintignore

@@ -40,7 +40,7 @@ jobs:
           cache: npm
       - name: Install package dependencies
         run: npm ci
-      - name: Run ESLint
+      - name: Run Biome
         run: npm run lint
       - name: Run Knip
         run: npm run knip
@@ -56,7 +56,7 @@ jobs:
           cache: npm
       - name: Install package dependencies
         run: npm ci
-      - name: Run ESLint
+      - name: Run build check
         run: npm run build:check
   test-units-and-cover:
     name: Unit Tests And Coverage

.eslintrc.js

@@ -0,0 +1,22 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - reopened
+
+jobs:
+  pr-title-lint:
+    name: Lint PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: PR title must follow Conventional Commits format (e.g. "feat: add feature" or "fix(scope): fix bug").

.github/workflows/checks.yml

@@ -43,4 +43,6 @@ dist
 .nostr
 
 # Docker Compose overrides
-docker-compose.overrides.yml
+docker-compose.overrides.yml
+# Export output
+*.jsonl

.github/workflows/pr-title.yml

@@ -1,26 +1,26 @@
 {
   "all": true,
   "cache": true,
-  "branches": 80,
-  "lines": 80,
-  "functions": 80,
-  "statements": 80,
+  "branches": 47,
+  "lines": 54,
+  "functions": 48,
+  "statements": 55,
   "watermarks": {
     "lines": [
-      80,
-      95
+      54,
+      80
     ],
     "functions": [
-      80,
-      95
+      48,
+      80
     ],
     "branches": [
-      80,
-      95
+      47,
+      80
     ],
     "statements": [
-      80,
-      95
+      55,
+      80
     ]
   },
   "extension": [

.gitignore

@@ -119,4 +119,10 @@ Running `nostream` for the first time creates the settings file in `<project_roo
 | limits.message.ipWhitelist                  | List of IPs (IPv4 or IPv6) to ignore rate limits. |
 | limits.admissionCheck.rateLimits[].period          | Rate limit period in milliseconds. |
 | limits.admissionCheck.rateLimits[].rate            | Maximum number of admission checks during period. |
-| limits.admissionCheck.ipWhitelist                  | List of IPs (IPv4 or IPv6) to ignore rate limits. |
+| limits.admissionCheck.ipWhitelist                  | List of IPs (IPv4 or IPv6) to ignore rate limits. |
+| nip05.mode                                  | NIP-05 verification mode: `enabled` requires verification, `passive` verifies without blocking, `disabled` does nothing. Defaults to `disabled`. |
+| nip05.verifyExpiration                      | Time in milliseconds before a successful NIP-05 verification expires and needs re-checking. Defaults to 604800000 (1 week). |
+| nip05.verifyUpdateFrequency                 | Minimum interval in milliseconds between re-verification attempts for a given author. Defaults to 86400000 (24 hours). |
+| nip05.maxConsecutiveFailures                | Number of consecutive verification failures before giving up on an author. Defaults to 20. |
+| nip05.domainWhitelist                       | List of domains allowed for NIP-05 verification. If set, only authors verified at these domains can publish. |
+| nip05.domainBlacklist                       | List of domains blocked from NIP-05 verification. Authors with NIP-05 at these domains will be rejected. |

.nycrc.json

@@ -14,7 +14,7 @@ Run dead code and dependency analysis before opening a pull request:
 npm run knip
 ```
 
-`npm run lint` now runs Knip first, then ESLint.
+`npm run lint` now runs Biome.
 
 ## Pull Request Process
 
@@ -24,3 +24,12 @@ npm run knip
    Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
 3. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
    do not have permission to do that, you may request the second reviewer to merge it for you.
+
+## Code Quality
+
+Run Biome checks before opening a pull request:
+
+```
+npm run lint
+npm run format:check
+```

CONFIGURATION.md

@@ -470,6 +470,17 @@ Start:
 
 ## Tests
 
+### Linting and formatting (Biome)
+
+Run code quality checks with Biome:
+
+  ```
+  npm run lint
+  npm run lint:fix
+  npm run format
+  npm run format:check
+  ```
+
 ### Unit tests
 
 Open a terminal and change to the project's directory:
@@ -570,6 +581,101 @@ To see the integration test coverage report open `.coverage/integration/lcov-rep
   open .coverage/integration/lcov-report/index.html
   ```
 
+
+## Security & Load Testing
+
+Nostream includes a specialized security tester to simulate Slowloris-style connection holding and event flood (spam) attacks. This is used to verify relay resilience and prevent memory leaks.
+
+### Running the Tester
+  ```bash
+  # Simulates 5,000 idle "zombie" connections + 100 events/sec spam
+  npm run test:load -- --zombies 5000 --spam-rate 100
+  ```
+
+### Analyzing Memory (Heap Snapshots)
+To verify that connections are being correctly evicted and memory reclaimed:
+1. Ensure the relay is running with `--inspect` enabled (see `docker-compose.yml`).
+2. Open **Chrome DevTools** (`chrome://inspect`) and connect to the relay process.
+3. In the **Memory** tab, take a **Heap Snapshot** (Baseline).
+4. Run the load tester.
+5. Wait for the eviction cycle (default: 120s) and take a second **Heap Snapshot**.
+6. Switch the view to **Comparison** and select the Baseline snapshot.
+7. Verify that object counts (e.g., `WebSocketAdapter`, `SocketAddress`) return to baseline levels.
+
+### Server-Side Monitoring
+To observe client and subscription counts in real-time during a test, you can instrument `src/adapters/web-socket-server-adapter.ts`:
+
+1. Locate the `onHeartbeat()` method.
+2. Add the following logging logic:
+   ```typescript
+   private onHeartbeat() {
+     let totalSubs = 0;
+     let totalClients = 0;
+     this.webSocketServer.clients.forEach((webSocket) => {
+       totalClients++;
+       const webSocketAdapter = this.webSocketsAdapters.get(webSocket) as IWebSocketAdapter;
+       if (webSocketAdapter) {
+         webSocketAdapter.emit(WebSocketAdapterEvent.Heartbeat);
+         totalSubs += webSocketAdapter.getSubscriptions().size;
+       }
+     });
+     console.log(`[HEARTBEAT] Clients: ${totalClients} | Total subscriptions: ${totalSubs} | Heap Used: ${(process.memoryUsage().heapUsed / 1024 / 1024).toFixed(1)} MB`);
+   }
+   ```
+3. View the live output via Docker logs:
+   ```bash
+   docker compose logs -f nostream
+   ```
+=======
+## Export Events
+
+Export all stored events to a [JSON Lines](https://jsonlines.org/) (`.jsonl`) file. Each line is a valid NIP-01 Nostr event JSON object. The export streams rows from the database using cursors, so it works safely on relays with millions of events without loading them into memory.
+
+```
+npm run export                            # writes to events.jsonl
+npm run export -- backup-2024-01-01.jsonl # custom filename
+```
+
+The script reads the same `DB_*` environment variables used by the relay (see [CONFIGURATION.md](CONFIGURATION.md)).
+## Relay Maintenance
+
+Use `clean-db` to wipe or prune `events` table data. This also removes
+corresponding data from the derived `event_tags` table when present.
+
+Dry run (no deletion):
+
+  ```
+  npm run clean-db -- --all --dry-run
+  ```
+
+Full wipe:
+
+  ```
+  npm run clean-db -- --all --force
+  ```
+
+Delete events older than N days:
+
+  ```
+  npm run clean-db -- --older-than=30 --force
+  ```
+
+Delete only selected kinds:
+
+  ```
+  npm run clean-db -- --kinds=1,7,4 --force
+  ```
+
+Delete only selected kinds older than N days:
+
+  ```
+  npm run clean-db -- --older-than=30 --kinds=1,7,4 --force
+  ```
+
+By default, the script asks for explicit confirmation (`Type 'DELETE' to confirm`).
+Use `--force` to skip the prompt.
+
+
 ## Configuration
 
 You can change the default folder by setting the `NOSTR_CONFIG_DIR` environment variable to a different path.

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.11/schema.json",
+	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+	"files": {
+		"ignoreUnknown": false,
+		"includes": [
+			"**",
+			"!**/node_modules/**",
+			"!**/dist/**",
+			"!**/.test-reports/**",
+			"!**/.coverage/**",
+			"!**/.nostr/**",
+			"!**/tslint.json"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "space",
+		"lineWidth": 120
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": false,
+			"correctness": { "noUnusedVariables": "error" },
+			"style": { "useBlockStatements": "warn" },
+			"suspicious": { "noExplicitAny": "off" }
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single",
+			"semicolons": "asNeeded",
+			"trailingCommas": "all"
+		}
+	}
+}