Merge branch 'main' into fix-serialize-javascript

cameri · web-flow · commit bb0c9a174547 · 2026-05-03T13:37:19.000-04:00
diff --git a/.changeset/geohash-prefix-filters.md b/.changeset/geohash-prefix-filters.md
@@ -0,0 +1,9 @@
+---
+"nostream": patch
+---
+
+Implement geohash wildcard/prefix behavior for `#g` filters (closes #265): a
+criterion ending in `*` matches any event `g` tag whose value starts with the
+prefix before `*`; exact matching (no `*`) is unchanged. Only normal geohash
+prefixes are intended as input. This is a Nostream extension, not part of
+NIP-12.
diff --git a/.changeset/husky-fallback.md b/.changeset/husky-fallback.md
@@ -0,0 +1,5 @@
+---
+"nostream": patch
+---
+
+fix: add husky install fallback for non-dev environments
diff --git a/.changeset/jolly-canyons-glow.md b/.changeset/jolly-canyons-glow.md
@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+perf: added k6 performance tests for connection and message rate limiting
diff --git a/.husky/install.mjs b/.husky/install.mjs
@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+// Skip Husky installation in environments where hooks are not needed
+if (
+  process.env.NODE_ENV === 'production' ||
+  process.env.CI === 'true' ||
+  process.env.HUSKY === '0' ||
+  !existsSync('.git')
+) {
+  process.exit(0);
+}
+
+try {
+  execSync('npx husky install', { stdio: 'ignore' });
+} catch {
+  process.exit(0);
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -302,6 +302,41 @@ To observe client and subscription counts in real-time during a test, you can in
    docker compose logs -f nostream
    ```
 
+## Performance Testing (k6)
+
+Nostream includes k6-based load tests to validate rate limiter behavior under concurrent WebSocket
+connections. These tests verify that connection and message rate limits are correctly enforced.
+
+### Prerequisites
+
+Install [k6](https://grafana.com/docs/k6/latest/set-up/install-k6/) before running performance
+tests. k6 is a standalone Go binary and is not included as an npm dependency.
+
+### Running the Tests
+
+Ensure the relay is running first (`pnpm run cli -- start`), then:
+
+```bash
+# Test connection rate limiting
+pnpm run cli -- dev test:perf:connection
+
+# Test message rate limiting
+pnpm run cli -- dev test:perf:message
+```
+
+To test against a different relay instance:
+
+```bash
+k6 run -e RELAY_URL=ws://your-host:8008 test/performance/connection-limiting-k6.ts
+```
+
+### What the Tests Validate
+
+- **Connection rate limiter** — Ramps concurrent connections through multiple stages and verifies
+  the relay rejects excess connections beyond the configured limit (default: 12 conn/sec).
+- **Message rate limiter** — Opens WebSocket connections and sends continuous REQ messages,
+  verifying the relay returns NOTICE rejections when the message rate limit is exceeded.
+
 ## Local Quality Checks
 
 Run dead code and dependency analysis before opening a pull request:
diff --git a/package.json b/package.json
@@ -76,6 +76,8 @@
     "test:load": "node -r ts-node/register ./scripts/security-load-test.ts",
     "smoke:nip03": "node -r ts-node/register scripts/smoke-nip03.ts",
     "test:integration": "cucumber-js",
+    "test:performance:connection-rate-limit": "k6 run test/performance/connection-limiting-k6.ts",
+    "test:performance:message-rate-limit": "k6 run test/performance/message-limiting-k6.ts",
     "cover:integration": "nyc --report-dir .coverage/integration pnpm run test:integration -p cover",
     "export": "node --env-file-if-exists=.env -r ts-node/register src/scripts/export-events.ts",
     "docker:compose:start": "pnpm run cli -- start",
@@ -93,7 +95,7 @@
     "docker:cover:integration": "pnpm run docker:integration:run pnpm exec nyc --report-dir .coverage/integration pnpm run test:integration -- -p cover",
     "postdocker:integration:run": "docker compose -f ./test/integration/docker-compose.yml down",
     "prepack": "pnpm run build",
-    "prepare": "husky install || exit 0",
+    "prepare": "test -f .husky/install.mjs && node .husky/install.mjs || true",
     "changeset:version": "changeset version && pnpm install --lockfile-only",
     "changeset:publish": "changeset publish"
   },
@@ -124,6 +126,7 @@
     "@types/chai-as-promised": "^7.1.5",
     "@types/express": "4.17.21",
     "@types/js-yaml": "4.0.5",
+    "@types/k6": "^1.7.0",
     "@types/mocha": "^9.1.1",
     "@types/node": "^24.12.2",
     "@types/pg": "^8.6.5",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/cli/commands/dev.ts b/src/cli/commands/dev.ts
@@ -137,3 +137,21 @@ export const runDevTestIntegration = async (): Promise<number> => {
     () => runCommand('pnpm', ['run', 'test:integration']),
   )
 }
+
+export const runDevTestPerfConnection = async (): Promise<number> => {
+  return runWithSpinner(
+    'Running connection rate limit performance test...',
+    'Connection rate limit test completed',
+    'Connection rate limit test failed',
+    () => runCommand('k6', ['run', 'test/performance/connection-limiting-k6.ts']),
+  )
+}
+
+export const runDevTestPerfMessage = async (): Promise<number> => {
+  return runWithSpinner(
+    'Running message rate limit performance test...',
+    'Message rate limit test completed',
+    'Message rate limit test failed',
+    () => runCommand('k6', ['run', 'test/performance/message-limiting-k6.ts']),
+  )
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
@@ -28,6 +28,8 @@ import {
   runDevTestCli,
   runDevTestIntegration,
   runDevTestUnit,
+  runDevTestPerfConnection,
+  runDevTestPerfMessage
 } from './commands/dev'
 import { runTui } from './tui/main'
 import { logError, logInfo } from './utils/output'
@@ -97,6 +99,8 @@ const devSubHelp: Record<string, string> = {
   'test:unit': 'Usage: nostream dev test:unit',
   'test:cli': 'Usage: nostream dev test:cli',
   'test:integration': 'Usage: nostream dev test:integration',
+  'test:perf:connection': 'Usage: nostream dev test:perf:connection',
+  'test:perf:message': 'Usage: nostream dev test:perf:message',
 }
 
 const withErrorBoundary =
@@ -410,6 +414,10 @@ cli
           return runDevTestCli()
         case 'test:integration':
           return runDevTestIntegration()
+        case 'test:perf:connection':
+          return runDevTestPerfConnection()
+        case 'test:perf:message':
+          return runDevTestPerfMessage()
         default:
           logInfo(
             'Usage: nostream dev <db:clean|db:reset|seed:relay|docker:clean|test:unit|test:cli|test:integration> [args]',
diff --git a/src/constants/base.ts b/src/constants/base.ts
@@ -56,6 +56,8 @@ export enum EventTags {
   Invoice = 'bolt11',
   // NIP-03: target event kind on an OpenTimestamps attestation
   Kind = 'k',
+  // NIP-12: geohash tag for location-based queries
+  Geohash = 'g',
 }
 
 export const ALL_RELAYS = 'ALL_RELAYS'
diff --git a/src/repositories/event-repository.ts b/src/repositories/event-repository.ts
@@ -40,7 +40,7 @@ import { DBEvent, Event } from '../@types/event'
 import { EventPurgeCounts, EventRetentionOptions, IEventRepository, IQueryResult } from '../@types/repositories'
 import { toBuffer, toJSON } from '../utils/transform'
 import { createLogger } from '../factories/logger-factory'
-import { isGenericTagQuery } from '../utils/filter'
+import { isGenericTagQuery, isGeohashPrefixCriterion, stripGeohashPrefixWildcard } from '../utils/filter'
 import { SubscriptionFilter } from '../@types/subscription'
 
 const even = pipe(modulo(__, 2), equals(0))
@@ -193,8 +193,21 @@ export class EventRepository implements IEventRepository {
             isEmpty,
             () => andWhereRaw('1 = 0', bd),
             forEach(
-              (criterion: string) =>
-                void orWhereRaw('event_tags.tag_name = ? AND event_tags.tag_value = ?', [filterName[1], criterion], bd),
+              (criterion: string) => {
+                if (isGeohashPrefixCriterion(filterName, criterion)) {
+                  return void orWhereRaw(
+                    'event_tags.tag_name = ? AND event_tags.tag_value LIKE ?',
+                    [filterName[1], `${stripGeohashPrefixWildcard(criterion)}%`],
+                    bd,
+                  )
+                }
+
+                return void orWhereRaw(
+                  'event_tags.tag_name = ? AND event_tags.tag_value = ?',
+                  [filterName[1], criterion],
+                  bd,
+                )
+              },
             ),
           )(criteria)
         })
diff --git a/src/schemas/base-schema.ts b/src/schemas/base-schema.ts
@@ -1,7 +1,13 @@
 import { z } from 'zod'
 
+import { GEOHASH_FILTER_PATTERN, GEOHASH_PATTERN } from '../utils/geohash'
+
 const lowerHexRegex = /^[0-9a-f]+$/
 
+// NIP-12 geohash schemas
+export const geohashSchema = z.string().regex(GEOHASH_PATTERN, 'Invalid geohash')
+export const geohashFilterValueSchema = z.string().regex(GEOHASH_FILTER_PATTERN, 'Invalid geohash filter')
+
 export const prefixSchema = z.string().regex(lowerHexRegex).min(4).max(64)
 
 export const idSchema = z.string().regex(lowerHexRegex).length(64)
diff --git a/src/schemas/event-schema.ts b/src/schemas/event-schema.ts
@@ -1,7 +1,15 @@
 import { z } from 'zod'
 
 import { EventKinds, EventTags } from '../constants/base'
-import { createdAtSchema, idSchema, kindSchema, pubkeySchema, signatureSchema, tagSchema } from './base-schema'
+import {
+  createdAtSchema,
+  geohashSchema,
+  idSchema,
+  kindSchema,
+  pubkeySchema,
+  signatureSchema,
+  tagSchema,
+} from './base-schema'
 
 /**
  * {
@@ -42,4 +50,15 @@ export const eventSchema = z
         }
       })
     }
+
+    // Validate geohash tag values (NIP-12 #g)
+    event.tags.forEach((tag, index) => {
+      if (tag[0] === EventTags.Geohash && typeof tag[1] === 'string' && !geohashSchema.safeParse(tag[1]).success) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Invalid geohash',
+          path: ['tags', index, 1],
+        })
+      }
+    })
   })
diff --git a/src/schemas/filter-schema.ts b/src/schemas/filter-schema.ts
@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
-import { createdAtSchema, kindSchema, prefixSchema } from './base-schema'
-import { isGenericTagQuery } from '../utils/filter'
+import { createdAtSchema, geohashFilterValueSchema, kindSchema, prefixSchema } from './base-schema'
+import { isGenericTagQuery, isGeohashTagQuery } from '../utils/filter'
 
 const knownFilterKeys = new Set(['ids', 'authors', 'kinds', 'since', 'until', 'limit'])
 
@@ -16,13 +16,27 @@ export const filterSchema = z
   })
   .catchall(z.array(z.string().max(1024)))
   .superRefine((data, ctx) => {
-    for (const key of Object.keys(data)) {
+    for (const [key, value] of Object.entries(data)) {
       if (!knownFilterKeys.has(key) && !isGenericTagQuery(key)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message: `Unknown key: ${key}`,
           path: [key],
         })
+        continue
+      }
+
+      // Validate #g filter values: NIP-12 geohash with optional single trailing '*'
+      if (isGeohashTagQuery(key) && Array.isArray(value)) {
+        value.forEach((criterion, index) => {
+          if (typeof criterion === 'string' && !geohashFilterValueSchema.safeParse(criterion).success) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: 'Invalid geohash filter',
+              path: [key, index],
+            })
+          }
+        })
       }
     }
   })
diff --git a/src/utils/event.ts b/src/utils/event.ts
@@ -8,7 +8,7 @@ import { deriveFromSecret } from './secret'
 import { EventKindsRange } from '../@types/settings'
 import { fromBuffer } from './transform'
 import { getLeadingZeroBits } from './proof-of-work'
-import { isGenericTagQuery } from './filter'
+import { isGenericTagQuery, isGeohashPrefixCriterion, stripGeohashPrefixWildcard } from './filter'
 import { SubscriptionFilter } from '../@types/subscription'
 import { WebSocketServerAdapterEvent } from '../constants/adapter'
 
@@ -40,6 +40,18 @@ export const isEventMatchingFilter =
   (filter: SubscriptionFilter) =>
   (event: Event): boolean => {
     const startsWith = (input: string) => (prefix: string) => input.startsWith(prefix)
+    const isMatchingGenericTagCriterion = (key: string, criterion: string) => (tag: Tag): boolean => {
+      const [, tagName] = key
+      if (tag[0] !== tagName) {
+        return false
+      }
+
+      if (isGeohashPrefixCriterion(key, criterion)) {
+        return tag[1].startsWith(stripGeohashPrefixWildcard(criterion))
+      }
+
+      return tag[1] === criterion
+    }
 
     // NIP-01: Basic protocol flow description
 
@@ -84,7 +96,7 @@ export const isEventMatchingFilter =
       Object.entries(filter)
         .filter(([key, criteria]) => isGenericTagQuery(key) && Array.isArray(criteria))
         .some(([key, criteria]) => {
-          return !event.tags.some((tag) => tag[0] === key[1] && criteria.includes(tag[1]))
+          return !event.tags.some((tag) => criteria.some((criterion) => isMatchingGenericTagCriterion(key, criterion)(tag)))
         })
     ) {
       return false
diff --git a/src/utils/filter.ts b/src/utils/filter.ts
@@ -1 +1,13 @@
+import { EventTags } from '../constants/base'
+
 export const isGenericTagQuery = (key: string) => /^#[a-zA-Z]$/.test(key)
+
+// NIP-12 geohash filter helpers
+export const geohashTagQuery = `#${EventTags.Geohash}`
+
+export const isGeohashTagQuery = (key: string): boolean => key === geohashTagQuery
+
+export const isGeohashPrefixCriterion = (key: string, criterion: string): boolean =>
+  isGeohashTagQuery(key) && criterion.endsWith('*')
+
+export const stripGeohashPrefixWildcard = (criterion: string): string => criterion.slice(0, -1)
diff --git a/src/utils/geohash.ts b/src/utils/geohash.ts
@@ -0,0 +1,9 @@
+// Geohash base32 alphabet (excludes 'a', 'i', 'l', 'o')
+export const GEOHASH_BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz'
+
+// Matches a complete geohash (one or more base32 chars)
+export const GEOHASH_PATTERN = /^[0123456789bcdefghjkmnpqrstuvwxyz]+$/
+
+// Matches a geohash filter criterion: one or more base32 chars, with an
+// optional single trailing '*' wildcard (NIP-12 prefix matching)
+export const GEOHASH_FILTER_PATTERN = /^[0123456789bcdefghjkmnpqrstuvwxyz]+\*?$/
diff --git a/test/performance/connection-limiting-k6.ts b/test/performance/connection-limiting-k6.ts
diff --git a/test/performance/message-limiting-k6.ts b/test/performance/message-limiting-k6.ts
diff --git a/test/unit/husky/install.spec.ts b/test/unit/husky/install.spec.ts
diff --git a/test/unit/repositories/event-repository.spec.ts b/test/unit/repositories/event-repository.spec.ts
diff --git a/test/unit/schemas/event-schema.spec.ts b/test/unit/schemas/event-schema.spec.ts
diff --git a/test/unit/schemas/filter-schema.spec.ts b/test/unit/schemas/filter-schema.spec.ts
diff --git a/test/unit/utils/event.spec.ts b/test/unit/utils/event.spec.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"nostream": patch
 +---
++
 +fix: add husky install fallback for non-dev environments
Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,8 @@ export enum EventTags {`
`56`	`56`	`Invoice = 'bolt11',`
`57`	`57`	`// NIP-03: target event kind on an OpenTimestamps attestation`
`58`	`58`	`Kind = 'k',`
	`59`	`+ // NIP-12: geohash tag for location-based queries`
	`60`	`+ Geohash = 'g',`
`59`	`61`	`}`
`60`	`62`
`61`	`63`	`export const ALL_RELAYS = 'ALL_RELAYS'`