Jon Staab
82 lines
2.3 KiB
Markdown
82 lines
2.3 KiB
Markdown
# @welshman/net
|
|
|
|
[](https://npmjs.com/package/@welshman/net)
|
|
|
|
Core networking layer for nostr applications, handling relay connections, message management, and event delivery.
|
|
|
|
## What's Included
|
|
|
|
- **Connection Management** - WebSocket lifecycle and relay connections
|
|
- **Subscription System** - Event filtering and subscription handling
|
|
- **Publishing Tools** - Event broadcasting with status tracking
|
|
- **Sync Utilities** - NIP-77 (negentropy) event synchronization
|
|
- **Connection Pool** - Shared relay connection management
|
|
- **Targets** - Flexible message routing strategies
|
|
- **Event Tracking** - Monitor which relays have seen events
|
|
|
|
## Quick Example
|
|
|
|
```typescript
|
|
import {ctx, setContext} from '@welshman/lib'
|
|
import {type TrustedEvent, createEvent, NOTE} from '@welshman/util'
|
|
import {subscribe, publish, getDefaultNetContext} from '@welshman/net'
|
|
|
|
// Sets up customizable event valdation, handlers, etc
|
|
setContext(getDefaultNetContext())
|
|
|
|
// Send a subscription
|
|
const sub = subscribe({
|
|
relays: ['wss://relay.example.com/'],
|
|
filters: [{kinds: [1], limit: 1}],
|
|
closeOnEose: true,
|
|
timeout: 10000,
|
|
})
|
|
|
|
sub.on(SubscriptionEvent.Event, (url: string, event: TrustedEvent) => {
|
|
console.log(url, event)
|
|
sub.close()
|
|
})
|
|
|
|
// Publish an event
|
|
const pub = publish({
|
|
relays: ['wss://relay.example.com/'],
|
|
event: createEvent(NOTE, {content: 'hi'}),
|
|
})
|
|
|
|
pub.emitter.on('*', (status: PublishStatus, url: string) => {
|
|
console.log(status, url)
|
|
})
|
|
|
|
// The Tracker class can tell you which relays an event was read from or published to
|
|
console.log(ctx.net.tracker.getRelays(event.id))
|
|
```
|
|
|
|
The main reason this module exists is to support different backends via Executor and different `target` classes. For example, to add a local relay that automatically gets used:
|
|
|
|
```typescript
|
|
import {setContext} from '@welshman/lib'
|
|
import {LOCAL_RELAY_URL, Relay, Repository} from '@welshman/util'
|
|
import {getDefaultNetContext, Multi, Local, Relays, Executor} from '@welshman/net'
|
|
|
|
const repository = new Repository()
|
|
|
|
const relay = new Relay(repository)
|
|
|
|
setContext(getDefaultNetContext({
|
|
getExecutor: (relays: string[]) => {
|
|
return new Executor(
|
|
new Multi([
|
|
new Local(relay),
|
|
new Relays(remoteUrls.map(url => ctx.net.pool.get(url))),
|
|
])
|
|
)
|
|
},
|
|
}))
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @welshman/net
|
|
```
|