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

Author: cameri

.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,21 +123,23 @@ 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
+          name: integration-coverage-lcov
+          path: .coverage/integration/lcov.info
   sonarcloud:
     name: Sonarcloud
     needs: [test-units-and-cover, test-integrations-and-cover]
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         name: Download unit & integration coverage reports
         with:
           path: .coverage

.gitignore

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

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

scripts/start

@@ -19,6 +19,45 @@ if [ "$EUID" -eq 0 ]
   exit 1
 fi
 
+# ── DNS Pre-flight Check ─────────────────────────────────────────────
+YELLOW=$'\033[0;33m'
+BOLD_YELLOW=$'\033[1;33m'
+NC=$'\033[0m'
+DNS_TEST_URL="https://dl-cdn.alpinelinux.org"
+DNS_MAX_RETRIES=3
+DNS_OK=false
+BACKOFF=2
+
+echo "Checking Docker DNS connectivity..."
+for i in $(seq 1 $DNS_MAX_RETRIES); do
+  printf "  [Attempt $i/$DNS_MAX_RETRIES] Testing resolution... "
+  if docker run --rm alpine wget --spider --timeout=5 "$DNS_TEST_URL" > /dev/null 2>&1; then
+    echo "Success"
+    DNS_OK=true
+    break
+  else
+    echo "Failed"
+  fi
+  [ "$i" -lt "$DNS_MAX_RETRIES" ] && sleep $BACKOFF && BACKOFF=$((BACKOFF * 2))
+done
+
+if [ "$DNS_OK" = false ]; then
+  cat <<EOF >&2
+
+${BOLD_YELLOW}  WARNING: Docker DNS resolution failed after $DNS_MAX_RETRIES attempts.${NC}
+${YELLOW}   Containers cannot resolve external domains (e.g. dl-cdn.alpinelinux.org).
+   This is commonly caused by a DNS bridge conflict with systemd-resolved.
+
+   Suggested fixes:
+     1. Add DNS to /etc/docker/daemon.json:
+        { "dns": ["8.8.8.8", "8.8.4.4"] }
+     2. Then run sudo systemctl restart docker
+
+   The build will continue, but may fail during package installation.${NC}
+
+EOF
+fi
+
 if [[ ! -d "${NOSTR_CONFIG_DIR}" ]]; then
   echo "Creating folder ${NOSTR_CONFIG_DIR}"
   mkdir -p "${NOSTR_CONFIG_DIR}"

src/@types/repositories.ts

@@ -17,6 +17,8 @@ export interface IEventRepository {
   upsert(event: Event): Promise<number>
   findByFilters(filters: SubscriptionFilter[]): IQueryResult<DBEvent[]>
   deleteByPubkeyAndIds(pubkey: Pubkey, ids: EventId[]): Promise<number>
+  deleteByPubkeyExceptKinds(pubkey: Pubkey, excludedKinds: number[]): Promise<number>
+  hasActiveRequestToVanish(pubkey: Pubkey): Promise<boolean>
 }
 
 export interface IInvoiceRepository {

src/constants/base.ts

@@ -7,6 +7,7 @@ export enum EventKinds {
   DELETE = 5,
   REPOST = 6,
   REACTION = 7,
+  REQUEST_TO_VANISH = 62,
   // Channels
   CHANNEL_CREATION = 40,
   CHANNEL_METADATA = 41,
@@ -36,12 +37,15 @@ export enum EventKinds {
 export enum EventTags {
   Event = 'e',
   Pubkey = 'p',
+  Relay = 'r',
   //  Multicast = 'm',
   Deduplication = 'd',
   Expiration = 'expiration',
   Invoice = 'bolt11',
 }
 
+export const ALL_RELAYS = 'ALL_RELAYS'
+
 export enum PaymentsProcessors {
   LNURL = 'lnurl',
   ZEBEDEE = 'zebedee',

src/factories/event-strategy-factory.ts

@@ -1,4 +1,4 @@
-import { isDeleteEvent, isEphemeralEvent, isParameterizedReplaceableEvent, isReplaceableEvent } from '../utils/event'
+import { isDeleteEvent, isEphemeralEvent, isParameterizedReplaceableEvent, isReplaceableEvent, isRequestToVanishEvent } from '../utils/event'
 import { DefaultEventStrategy } from '../handlers/event-strategies/default-event-strategy'
 import { DeleteEventStrategy } from '../handlers/event-strategies/delete-event-strategy'
 import { EphemeralEventStrategy } from '../handlers/event-strategies/ephemeral-event-strategy'
@@ -9,12 +9,15 @@ import { IEventStrategy } from '../@types/message-handlers'
 import { IWebSocketAdapter } from '../@types/adapters'
 import { ParameterizedReplaceableEventStrategy } from '../handlers/event-strategies/parameterized-replaceable-event-strategy'
 import { ReplaceableEventStrategy } from '../handlers/event-strategies/replaceable-event-strategy'
+import { VanishEventStrategy } from '../handlers/event-strategies/vanish-event-strategy'
 
 export const eventStrategyFactory = (
   eventRepository: IEventRepository,
 ): Factory<IEventStrategy<Event, Promise<void>>, [Event, IWebSocketAdapter]> =>
   ([event, adapter]: [Event, IWebSocketAdapter]) => {
-    if (isReplaceableEvent(event)) {
+    if (isRequestToVanishEvent(event)) {
+      return new VanishEventStrategy(adapter, eventRepository)
+    } else if (isReplaceableEvent(event)) {
       return new ReplaceableEventStrategy(adapter, eventRepository)
     } else if (isEphemeralEvent(event)) {
       return new EphemeralEventStrategy(adapter)

src/factories/message-handler-factory.ts

@@ -18,6 +18,7 @@ export const messageHandlerFactory = (
         return new EventMessageHandler(
           adapter,
           eventStrategyFactory(eventRepository),
+          eventRepository,
           userRepository,
           createSettings,
           slidingWindowRateLimiterFactory,