Merge branch 'main' into fix/nip01-replaceable-tiebreaker

Author: YashIIT0909

.env.example

@@ -0,0 +1,69 @@
+# --- REQUIRED ---
+SECRET=change_me_to_something_long_and_random # Generate: openssl rand -hex 128
+
+# --- POSTGRESQL ---
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=nostr_ts_relay
+DB_USER=nostr_ts_relay
+DB_PASSWORD=nostr_ts_relay
+# Alternatively, use a URI:
+# DB_URI=postgresql://nostr_ts_relay:nostr_ts_relay@localhost:5432/nostr_ts_relay
+
+# --- DB POOL TUNING (Optional) ---
+# DB_MIN_POOL_SIZE=0
+# DB_MAX_POOL_SIZE=3
+# DB_ACQUIRE_CONNECTION_TIMEOUT=60000
+
+# --- REDIS (Required for Rate Limiting) ---
+REDIS_HOST=localhost
+REDIS_PORT=6379
+# REDIS_USER=default
+# REDIS_PASSWORD=
+# Alternatively, use a URI:
+# REDIS_URI=redis://localhost:6379
+
+# --- SERVER CONFIG ---
+RELAY_PORT=8008
+WORKER_COUNT=2 # Defaults to CPU count. Use 1 or 2 for local testing.
+# NOSTR_CONFIG_DIR=.nostr # Where settings.yaml lives
+
+# --- DEBUGGING ---
+# Useful namespaces: maintenance-worker, database-client:*, cache-client, etc.
+# DEBUG=maintenance-worker
+
+# --- RELAY PRIVATE KEY (Optional) ---
+# RELAY_PRIVATE_KEY=your_hex_private_key
+
+# --- PAYMENTS (Only if enabled in settings.yaml) ---
+# ZEBEDEE_API_KEY=
+# NODELESS_API_KEY=
+# NODELESS_WEBHOOK_SECRET=
+# OPENNODE_API_KEY=
+# LNBITS_API_KEY=
+
+# --- READ REPLICAS (Optional) ---
+# READ_REPLICA_ENABLED=false
+# READ_REPLICAS=2
+# RR0_DB_HOST=localhost
+# RR0_DB_PORT=5432
+# RR0_DB_NAME=nostr_ts_relay
+# RR0_DB_USER=your_psql_username
+# RR0_DB_PASSWORD=your_psql_password
+# RR0_DB_MIN_POOL_SIZE=0
+# RR0_DB_MAX_POOL_SIZE=3
+# RR0_DB_ACQUIRE_CONNECTION_TIMEOUT=60000
+# RR1_DB_HOST=localhost
+# RR1_DB_PORT=5432
+# RR1_DB_NAME=nostr_ts_relay
+# RR1_DB_USER=your_psql_username
+# RR1_DB_PASSWORD=your_psql_password
+# RR1_DB_MIN_POOL_SIZE=0
+# RR1_DB_MAX_POOL_SIZE=3
+# RR1_DB_ACQUIRE_CONNECTION_TIMEOUT=60000
+
+# --- TOR (Optional) ---
+# TOR_HOST=localhost
+# TOR_CONTROL_PORT=9051
+# TOR_PASSWORD=
+# HIDDEN_SERVICE_PORT=80

.github/workflows/checks.yml

@@ -77,11 +77,12 @@ jobs:
       - name: Run coverage for unit tests
         run: npm run cover:unit
         if: ${{ always() }}
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         name: Upload coverage report for unit tests
         if: ${{ always() }}
         with:
-          path: .coverage/*/lcov.info
+          name: unit-coverage-lcov
+          path: .coverage/unit/lcov.info
       - name: Coveralls
         uses: coverallsapp/github-action@master
         if: ${{ always() }}
@@ -122,29 +123,12 @@ jobs:
           flag-name: Integration
           parallel: true
           github-token: ${{ secrets.GITHUB_TOKEN }}
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         name: Upload coverage report for integration tests
         if: ${{ always() }}
         with:
-          path: .coverage/*/lcov.info
-  sonarcloud:
-    name: Sonarcloud
-    needs: [test-units-and-cover, test-integrations-and-cover]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - uses: actions/download-artifact@v3
-        name: Download unit & integration coverage reports
-        with:
-          path: .coverage
-      - name: SonarCloud Scan
-        uses: sonarsource/sonarcloud-github-action@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          name: integration-coverage-lcov
+          path: .coverage/integration/lcov.info
   post-tests:
     name: Post Tests
     needs: [test-units-and-cover, test-integrations-and-cover]

.gitignore

@@ -25,6 +25,11 @@ node_modules/
 .dccache
 .DS_Store
 
+# Local Setup
+redis.conf
+users.acl
+postgresql.local.conf
+
 # generate output
 dist
 

.nvmrc

@@ -1 +1 @@
-v18.8.0
+v24.14.1

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-alpine3.16 AS build
+FROM node:24-alpine AS build
 
 WORKDIR /build
 
@@ -10,7 +10,7 @@ COPY . .
 
 RUN npm run build
 
-FROM node:18-alpine3.16
+FROM node:24-alpine
 
 LABEL org.opencontainers.image.title="Nostream"
 LABEL org.opencontainers.image.source=https://github.com/cameri/nostream

Dockerfile.railwayapp

@@ -1,5 +1,5 @@
 ## Author Saransh Sharma @cynsar foundation
-FROM node:18-alpine3.16 as build
+FROM node:24-alpine as build
 
 ARG PORT
 ARG PGHOST
@@ -29,7 +29,7 @@ COPY . .
 
 RUN npm run build
 
-FROM node:18-alpine3.16
+FROM node:24-alpine
 
 ARG PORT
 ARG PGHOST

Dockerfile.test

@@ -1,4 +1,4 @@
-FROM node:18-alpine3.16
+FROM node:24-alpine
 
 WORKDIR /code
 

README.md

@@ -67,7 +67,7 @@ NIPs with a relay-specific implementation are listed here.
 ### Standalone setup
 - PostgreSQL 14.0
 - Redis
-- Node v18
+- Node v24
 - Typescript
 
 ### Docker setups
@@ -230,6 +230,29 @@ Print the Tor hostname:
   ./scripts/print_tor_hostname
   ```
 
+### Importing events from JSON Lines
+
+You can import NIP-01 events from a `.jsonl` file directly into the relay database.
+
+Basic import:
+  ```
+  npm run import -- ./events.jsonl
+  ```
+
+Set a custom batch size (default: `1000`):
+  ```
+  npm run import -- ./events.jsonl --batch-size 500
+  ```
+
+The importer:
+
+- Processes the file line-by-line to keep memory usage bounded.
+- Validates NIP-01 schema, event id hash, and Schnorr signature before insertion.
+- Inserts in database transactions per batch.
+- Skips duplicates without failing the whole import.
+- Prints progress in the format:
+  `[Processed: 50,000 | Inserted: 45,000 | Skipped: 5,000 | Errors: 0]`
+
 ### Running as a Service
 
 By default this server will run continuously until you stop it with Ctrl+C or until the system restarts.

docker-compose.yml

@@ -114,7 +114,7 @@ services:
       retries: 5
 
   nostream-migrate:
-    image: node:18-alpine3.16
+    image: node:24-alpine
     container_name: nostream-migrate
     environment:
       DB_HOST: nostream-db

docs/REDIS.md

@@ -0,0 +1,145 @@
+# Redis
+
+Nostream uses Redis as a cache layer, currently for rate limiting incoming requests. This document covers how to configure Redis to work with Nostream, including the recommended ACL-based setup for production environments.
+
+## Overview
+
+Nostream uses Redis 7.0.5 (Alpine 3.16) and connects to it via the `redis` npm package (v4.5.1). Currently, Redis is used exclusively for rate limiting — throttling incoming requests from clients to prevent abuse.
+
+The Redis client is initialized as a singleton instance in `src/cache/client.ts`, meaning a single connection is shared across the entire application. This connection is wrapped by a `RedisAdapter` which exposes only the specific Redis operations
+Nostream needs.
+
+Rate limiting is implemented using a sliding window strategy, which uses Redis sorted sets to track request timestamps. This allows Nostream to accurately enforce rate limits over a rolling time window rather than a fixed one, preventing clients from bursting requests at window boundaries.
+
+## Requirements
+
+- Redis 6.0 or higher (for ACL support)
+- Nostream ships with Redis 7.0.5 (Alpine) by default via Docker Compose
+
+If you are using your own Redis instance instead of the one provided by Docker Compose, ensure it is running Redis 6.0 or higher to take advantage of the ACL configuration described in this document.
+
+## Configuration
+
+### Default Setup
+
+By default, Nostream connects to Redis using a single password on the default user via the `--requirepass` flag. This is configured in `docker-compose.yml`:
+
+```yaml
+command: redis-server --loglevel warning --requirepass nostr_ts_relay
+```
+
+While this works, it grants the connecting user full access to all Redis commands which is not recommended for production environments.
+
+Nostream reads the Redis connection details from the following environment variables:
+
+```
+REDIS_URI=redis://default:nostr_ts_relay@localhost:6379
+
+# or individually:
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_USER=default
+REDIS_PASSWORD=nostr_ts_relay
+```
+
+### ACL Setup (Recommended)
+
+Redis ACL (Access Control List), introduced in Redis 6.0, allows you to create restricted users that can only execute specific commands. This is recommended for production environments as it follows the principle of least privilege — Nostream only gets access to the commands it actually needs.
+
+#### Required Commands
+
+Nostream uses the following Redis commands internally:
+
+| Command | Used For |
+|---|---|
+| `EXISTS` | Checking if a rate limit key exists |
+| `GET` | Retrieving a cached value |
+| `SET` | Storing a cached value |
+| `ZADD` | Adding a request timestamp to the sliding window |
+| `ZRANGE` | Reading request timestamps from the sliding window |
+| `ZREMRANGEBYSCORE` | Removing expired timestamps from the sliding window |
+| `EXPIRE` | Setting expiry on rate limit keys |
+
+#### Example Configuration
+
+**Using redis.conf:**
+
+Add the following to your `redis.conf`:
+
+```conf
+aclfile /etc/redis/users.acl
+```
+
+Then create `/etc/redis/users.acl` with the following:
+
+```
+user nostream on >your_password ~* &* +EXISTS +GET +SET +ZADD +ZRANGE +ZREMRANGEBYSCORE +EXPIRE
+```
+
+**Using redis-cli:**
+
+You can also set the ACL rule directly via `redis-cli`:
+
+```bash
+ACL SETUSER nostream on >your_password ~* &* +EXISTS +GET +SET +ZADD +ZRANGE +ZREMRANGEBYSCORE +EXPIRE
+```
+
+Verify the user was created correctly:
+
+```bash
+ACL GETUSER nostream
+```
+
+**Updating docker-compose.yml:**
+
+Replace the default `--requirepass` flag with the ACL file approach:
+
+```yaml
+nostream-cache:
+    image: redis:7.0.5-alpine3.16
+    container_name: nostream-cache
+    volumes:
+        - cache:/data
+        - ./redis.conf:/usr/local/etc/redis/redis.conf
+        - ./users.acl:/etc/redis/users.acl
+    command: redis-server /usr/local/etc/redis/redis.conf
+    networks:
+      default:
+    restart: always
+    healthcheck:
+      test: [ "CMD", "redis-cli", "-u", "redis://nostream:your_password@localhost:6379", "ping" ]
+      interval: 1s
+      timeout: 5s
+      retries: 5
+```
+
+Then update your `.env` file:
+
+```
+REDIS_URI=redis://nostream:your_password@localhost:6379
+```
+
+## Troubleshooting
+
+**NOAUTH Authentication required**
+
+Redis is requiring authentication but no password was provided. Ensure your `REDIS_URI` or `REDIS_PASSWORD` environment variables are set correctly.
+
+**WRONGPASS invalid username-password pair**
+
+The username or password provided is incorrect. Double check your `REDIS_USER` and `REDIS_PASSWORD` environment variables match what was configured in your ACL setup.
+
+**NOPERM this user has no permissions to run the command**
+
+The Redis user does not have permission to run a specific command. Ensure all 7 required commands are granted in your ACL rule:
+
+```
++EXISTS +GET +SET +ZADD +ZRANGE +ZREMRANGEBYSCORE +EXPIRE
+```
+
+**Connection refused (ECONNREFUSED)**
+
+Redis is not running or is not reachable at the configured host and port. Verify:
+- Redis is running (`docker ps` if using Docker)
+- `REDIS_HOST` and `REDIS_PORT` are correct
+- No firewall is blocking the connection