Documentation
¶
Index ¶
- Constants
- Variables
- func GenerateConnectionURI(relayPubkey []byte, rendezvousRelay string, deviceName string) (uri string, secret []byte, err error)
- func MarshalResponseContent(resp *ResponseMessage) ([]byte, error)
- type AuthMode
- type Bridge
- func (b *Bridge) AddAuthorizedSecret(pubkeyHex, deviceName string)
- func (b *Bridge) ListAuthorizedSecrets() map[string]string
- func (b *Bridge) RemoveAuthorizedSecret(pubkeyHex string)
- func (b *Bridge) SessionCount() int
- func (b *Bridge) Start() error
- func (b *Bridge) Stop()
- func (b *Bridge) UpdateAuthorizedSecrets(secrets map[string]string)
- type BridgeConfig
- type ChunkMessage
- type Client
- func (c *Client) Close()
- func (c *Client) Connect(ctx context.Context) error
- func (c *Client) Count(ctx context.Context, subID string, filters ...*filter.F) (int64, error)
- func (c *Client) Publish(ctx context.Context, ev *event.E) (bool, string, error)
- func (c *Client) RelayURL() string
- func (c *Client) RequestIDs(ctx context.Context, subID string, filters ...*filter.F) ([]EventManifestEntry, error)
- func (c *Client) Subscribe(ctx context.Context, subID string, filters ...*filter.F) (<-chan *event.E, error)
- func (c *Client) Unsubscribe(ctx context.Context, subID string) error
- type ConnectionURI
- type EventManifestEntry
- type RequestMessage
- type ResponseMessage
- type Session
- func (s *Session) AddSubscription(subID string) error
- func (s *Session) Close()
- func (s *Session) Context() context.Context
- func (s *Session) Events() <-chan *SessionEvent
- func (s *Session) GetSubscription(subID string) *Subscription
- func (s *Session) HasSubscription(subID string) bool
- func (s *Session) IncrementEventCount(subID string)
- func (s *Session) IsExpired(timeout time.Duration) bool
- func (s *Session) MarkEOSE(subID string)
- func (s *Session) RemoveSubscription(subID string)
- func (s *Session) SendEvent(ev *SessionEvent) bool
- func (s *Session) SubscriptionCount() int
- func (s *Session) Touch()
- type SessionEvent
- type SessionManager
- func (m *SessionManager) CleanupExpired() int
- func (m *SessionManager) Close()
- func (m *SessionManager) Count() int
- func (m *SessionManager) Get(sessionID string) *Session
- func (m *SessionManager) GetOrCreate(sessionID string, clientPubkey, conversationKey []byte, authMode AuthMode, ...) *Session
- func (m *SessionManager) Remove(sessionID string)
- type Subscription
Constants ¶
const ( // KindNRCRequest is the event kind for NRC requests. KindNRCRequest = 24891 // KindNRCResponse is the event kind for NRC responses. KindNRCResponse = 24892 // MaxChunkSize is the maximum size for a single chunk (40KB to stay under 65KB limit after NIP-44 + base64). MaxChunkSize = 40000 )
Variables ¶
var ( ErrUnauthorized = errors.New("unauthorized") // ErrInvalidSession is returned when a session ID is invalid or not found. ErrInvalidSession = errors.New("invalid session") // ErrTooManySubscriptions is returned when a session has too many subscriptions. ErrTooManySubscriptions = errors.New("too many subscriptions") // ErrInvalidMessageType is returned when the message type is invalid. ErrInvalidMessageType = errors.New("invalid message type") // ErrSessionExpired is returned when a session has expired. ErrSessionExpired = errors.New("session expired") // ErrDecryptionFailed is returned when message decryption fails. ErrDecryptionFailed = errors.New("decryption failed") // ErrEncryptionFailed is returned when message encryption fails. ErrEncryptionFailed = errors.New("encryption failed") // ErrRelayConnectionFailed is returned when connection to the local relay fails. ErrRelayConnectionFailed = errors.New("relay connection failed") // ErrRendezvousConnectionFailed is returned when connection to the rendezvous relay fails. ErrRendezvousConnectionFailed = errors.New("rendezvous relay connection failed") )
Functions ¶
func GenerateConnectionURI ¶
func GenerateConnectionURI(relayPubkey []byte, rendezvousRelay string, deviceName string) (uri string, secret []byte, err error)
GenerateConnectionURI creates a new NRC connection URI with a random secret.
func MarshalResponseContent ¶
func MarshalResponseContent(resp *ResponseMessage) ([]byte, error)
MarshalResponseContent marshals an NRC response for encryption.
Types ¶
type Bridge ¶
type Bridge struct {
// contains filtered or unexported fields
}
Bridge connects a private relay to a public rendezvous relay.
func (*Bridge) AddAuthorizedSecret ¶
AddAuthorizedSecret adds an authorized secret (derived pubkey).
func (*Bridge) ListAuthorizedSecrets ¶
ListAuthorizedSecrets returns a copy of the authorized secrets map.
func (*Bridge) RemoveAuthorizedSecret ¶
RemoveAuthorizedSecret removes an authorized secret.
func (*Bridge) SessionCount ¶
SessionCount returns the number of active sessions.
func (*Bridge) Start ¶
Start starts the bridge and begins listening for NRC requests.
type BridgeConfig ¶
type BridgeConfig struct {
// RendezvousURL is the WebSocket URL of the public relay.
RendezvousURL string
// LocalRelayURL is the WebSocket URL of the local private relay.
LocalRelayURL string
// Signer is the relay's signer for signing response events.
Signer signer.I
// AuthorizedSecrets maps derived pubkeys to device names (secret-based auth).
AuthorizedSecrets map[string]string
// SessionTimeout is the inactivity timeout for sessions.
SessionTimeout time.Duration
}
BridgeConfig holds configuration for the NRC bridge.
type ChunkMessage ¶ added in v0.52.4
type ChunkMessage struct {
Type string `json:"type"` // Always "CHUNK"
MessageID string `json:"messageId"` // Unique ID for the chunked message
Index int `json:"index"` // 0-based chunk index
Total int `json:"total"` // Total number of chunks
Data string `json:"data"` // Base64 encoded chunk data
}
ChunkMessage represents a chunk of a large message.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client connects to a private relay through the NRC tunnel.
func NewClient ¶
NewClient creates a new NRC client from a connection URI.
func (*Client) Connect ¶
Connect establishes the connection to the rendezvous relay.
func (*Client) Count ¶
Count sends a COUNT request to the private relay.
func (*Client) Publish ¶
Publish publishes an event to the private relay.
func (*Client) RelayURL ¶
RelayURL returns a pseudo-URL for this NRC connection.
func (*Client) RequestIDs ¶ added in v0.52.4
func (c *Client) RequestIDs(ctx context.Context, subID string, filters ...*filter.F) ([]EventManifestEntry, error)
RequestIDs sends an IDS request to get event manifests for diffing.
type ConnectionURI ¶
type ConnectionURI struct {
// RelayPubkey is the public key of the private relay (32 bytes).
RelayPubkey []byte
// RendezvousRelay is the WebSocket URL of the public relay.
RendezvousRelay string
// AuthMode indicates the authentication mode.
AuthMode AuthMode
// DeviceName is an optional human-readable device identifier.
DeviceName string
// contains filtered or unexported fields
}
ConnectionURI represents a parsed nostr+relayconnect:// URI.
func ParseConnectionURI ¶
func ParseConnectionURI(nrcURI string) (conn *ConnectionURI, err error)
ParseConnectionURI parses a nostr+relayconnect:// URI.
URI format:
nostr+relayconnect://<relay-pubkey>?relay=<rendezvous-relay>&secret=<client-secret>[&name=<device-name>]
func (*ConnectionURI) GetClientSigner ¶
func (c *ConnectionURI) GetClientSigner() signer.I
GetClientSigner returns the signer derived from the secret (secret-based auth only).
func (*ConnectionURI) GetConversationKey ¶
func (c *ConnectionURI) GetConversationKey() []byte
GetConversationKey returns the NIP-44 conversation key (secret-based auth only).
type EventManifestEntry ¶ added in v0.52.4
type EventManifestEntry struct {
Kind int `json:"kind"`
ID string `json:"id"`
CreatedAt int64 `json:"created_at"`
D string `json:"d,omitempty"` // For parameterized replaceable events (kinds 30000-39999)
}
EventManifestEntry describes an event for manifest diffing (used by IDS).
type RequestMessage ¶
RequestMessage represents a parsed NRC request message.
func ParseRequestContent ¶
func ParseRequestContent(content []byte) (*RequestMessage, error)
ParseRequestContent parses the decrypted content of an NRC request.
type ResponseMessage ¶
type ResponseMessage struct {
Type string // EVENT, OK, EOSE, NOTICE, CLOSED, COUNT, AUTH, IDS, CHUNK
Payload []any
}
ResponseMessage represents an NRC response message to be sent.
type Session ¶
type Session struct {
// ID is the unique session identifier.
ID string
// ClientPubkey is the public key of the connected client.
ClientPubkey []byte
// ConversationKey is the NIP-44 conversation key for this session.
ConversationKey []byte
// DeviceName is the optional device identifier.
DeviceName string
// AuthMode is the authentication mode used.
AuthMode AuthMode
// CreatedAt is when the session was created.
CreatedAt time.Time
// LastActivity is the timestamp of the last activity.
LastActivity time.Time
// contains filtered or unexported fields
}
Session represents an NRC client session through the tunnel.
func NewSession ¶
func NewSession(id string, clientPubkey, conversationKey []byte, authMode AuthMode, deviceName string) *Session
NewSession creates a new session.
func (*Session) AddSubscription ¶
AddSubscription adds a new subscription to the session.
func (*Session) Context ¶
Context returns the session's context.
func (*Session) Events ¶
func (s *Session) Events() <-chan *SessionEvent
Events returns the channel for receiving events destined for this session.
func (*Session) GetSubscription ¶
func (s *Session) GetSubscription(subID string) *Subscription
GetSubscription returns a subscription by ID.
func (*Session) HasSubscription ¶
HasSubscription checks if a subscription exists.
func (*Session) IncrementEventCount ¶
IncrementEventCount increments the event count for a subscription.
func (*Session) IsExpired ¶
IsExpired checks if the session has been inactive too long.
func (*Session) MarkEOSE ¶
MarkEOSE marks a subscription as having sent EOSE.
func (*Session) RemoveSubscription ¶
RemoveSubscription removes a subscription from the session.
func (*Session) SendEvent ¶
func (s *Session) SendEvent(ev *SessionEvent) bool
SendEvent sends an event to the session's event channel.
func (*Session) SubscriptionCount ¶
SubscriptionCount returns the number of active subscriptions.
type SessionEvent ¶
type SessionEvent struct {
// Type is the response type (EVENT, OK, EOSE, NOTICE, CLOSED, COUNT, AUTH).
Type string
// Payload is the response payload array.
Payload []any
// RequestEventID is the ID of the request event this responds to (if applicable).
RequestEventID string
}
SessionEvent wraps a relay response for delivery to the client.
type SessionManager ¶
type SessionManager struct {
// contains filtered or unexported fields
}
SessionManager manages multiple NRC sessions.
func NewSessionManager ¶
func NewSessionManager(timeout time.Duration) *SessionManager
NewSessionManager creates a new session manager.
func (*SessionManager) CleanupExpired ¶
func (m *SessionManager) CleanupExpired() int
CleanupExpired removes expired sessions.
func (*SessionManager) Count ¶
func (m *SessionManager) Count() int
Count returns the number of active sessions.
func (*SessionManager) Get ¶
func (m *SessionManager) Get(sessionID string) *Session
Get returns a session by ID.
func (*SessionManager) GetOrCreate ¶
func (m *SessionManager) GetOrCreate(sessionID string, clientPubkey, conversationKey []byte, authMode AuthMode, deviceName string) *Session
GetOrCreate gets an existing session or creates a new one.
func (*SessionManager) Remove ¶
func (m *SessionManager) Remove(sessionID string)
Remove removes a session.
type Subscription ¶
type Subscription struct {
// ID is the client's subscription ID.
ID string
// CreatedAt is when the subscription was created.
CreatedAt time.Time
// EventCount tracks how many events have been sent.
EventCount int64
// EOSESent indicates whether EOSE has been sent.
EOSESent bool
}
Subscription represents a tunneled subscription.
Source Files
¶
- bridge.go
- client.go
- errors.go
- session.go
- uri.go