Re-write net docs

This commit is contained in:
Jon Staab
2025-06-10 15:07:58 -07:00
parent 5b73c507b7
commit 1a81768e8e
22 changed files with 580 additions and 840 deletions
+32 -52
View File
@@ -1,63 +1,43 @@
# Context
The Context system is the backbone of `@welshman/net`, providing global configuration and shared services that are essential for the package's operation. It defines how events are handled, validated, and routed throughout the application.
Provides global configuration and dependencies for the net package.
## Overview
## NetContext
- Global connection pool (`ctx.net.pool`)
- Event validation (`ctx.net.isValid`)
- Event handling (`ctx.net.onEvent`)
- Deletion tracking (`ctx.net.isDeleted`)
- Event signing (`ctx.net.signEvent`)
- Subscription optimization (`ctx.net.optimizeSubscriptions`)
Configuration object that defines how the net package operates:
## Basic Usage
- `pool: Pool` - Socket connection pool
- `repository: Repository` - Event storage and retrieval
- `isEventValid: (event, url) => boolean` - Event validation function
- `isEventDeleted: (event, url) => boolean` - Event deletion check
- `getAdapter?: (url, context) => AbstractAdapter` - Custom adapter factory
## Default Context
The `netContext` global provides sensible defaults:
- Uses singleton pool and repository instances
- Validates events using `verifyEvent`
- Checks deletions via repository
- No custom adapter factory
## Example
```typescript
import {ctx, setContext} from '@welshman/lib'
import {
getDefaultNetContext,
Pool,
hasValidSignature
} from '@welshman/net'
import {netContext} from '@welshman/net'
// Setup networking context
setContext({
net: getDefaultNetContext({
// Use shared pool
pool: new Pool(),
// Override event validation
netContext.isEventValid: (event, url) => {
return event.kind < 30000 && verifyEvent(event)
}
// Track events
onEvent: (url, event) => {
tracker.track(event.id, url)
repository.publish(event)
},
// Validate based on source
isValid: (url, event) => {
// Trust local relay
if (url === LOCAL_RELAY_URL) return true
// Validate signature for remote events
return hasValidSignature(event)
},
// Check deletion status
isDeleted: (url, event) =>
repository.isDeleted(event),
// Sign with current user
signEvent: async (event) =>
signer.get().sign(event)
})
// Use in requests
request({
filters: [{kinds: [1]}],
relays: ['wss://relay.example.com'],
context: {
...netContext,
// Request-specific overrides
}
})
// Now all package features will use these settings
subscribe(/*...*/) // Uses pool, validates events
publish(/*...*/) // Uses signEvent
```
The Context is used internally by most features in the package.
Without proper context configuration, core features like subscription, publishing, and event validation won't work correctly.
Think of it as the central configuration that defines how your nostr networking behaves.