strfry

README

strfry-tools

A set of tools for strfry relays for the Nostr protocol.

Included programs and plugins:

• strfry-config This will auto generate configs for a stryfry router, strfry relay and strfry-sync based on user pubkeys for streaming and syncing a network of contacts.
• strfry-sync This will sync a network of contacts using negentropy with strfry sync.
• strfry-down-plugin This is a write policy plugin for stryfry router and strfry relay to only allow specific event authors.

StrFry Config

This program (strfry-config) creates configuration files based on a set of configured root pubkeys. Their kind 3 (NIP-02) contact/follow lists and kind 10002 (NIP-65) relay list metadata ("outbox model") are retrieved for syncing and streaming events for them and their contacts through their relays.

There are several output files:

• A config file for a strfry router to have user specific relay-to-relay topology.
• A config for strfry-sync that uses negentropy to sync notes for complete and bandwidth efficient synchronization.
• A plugin config file for strfry router and strfry relay to only allow a set of pubkeys to write events.

Build & Install

make
cp strfry-config /usr/local/bin/strfry-config
cp strfry-down-plugin /usr/local/bin/strfry-down-plugin
cp sample-config.yml /etc/strfry-tools/config.yml

Then edit the config.yml to have your pubkey and other settings. You will likely also need to create directories such as /var/local/strfry-tools or similar.

You can also enable a service to keep it running, this will also include strfry router.

cp scripts/strfry-config.service /etc/systemd/system/strfry-config.service
cp scripts/strfry-router.service /etc/systemd/system/strfry-router.service

Then edit those scripts with your customizations and enable them with systemctl enable <name>.

Configuration

Example configuration (sample-router.yml):

log-level: "debug"

discovery-relays:
  - "wss://domain1.tld"
  - "wss://domian2.tld"

plugin-down: "/usr/bin/local/strfry-router-plugin"
plugin-config: "/var/local/strfry-tools/router-plugin"
router-config: "/var/local/strfry-tools/router.config"
router-timeout: "600"
sync-config: "/var/local/strfry-tools/sync.json"
sync-strfry: "/usr/bin/local/strfry"
sync-strfry-log: "/var/local/strfry-tools/logs/sync"
sync-status-file: "/var/local/strfry-tools/sync-status.json"

users:
  - name: "alice"
    pubkey: "<32-byte-public-key-hex>"
    depth: 1
    relay-depth: 1
    dir: down

Main options:

• log-level defines the verbosity of logs. The options include from less verbose to most: "panic", "fatal", "error", "warn", "info", "debug" and "trace".
• discovery-relays are used to retrieve the kind 10002 (NIP-65) relay list metadata for each pubkey that has been defined in users.
• plugin-down defines the location of the strfry-down-plugin executable for a strfry router and strfry relay.
• plugin-config defines the configuration base path for the strfry router plugin and strfry relay.
• router-config is the location of the strfry router configuration.
• router-timeout the timeout for a stream connection in strfry router.
• sync-config is the location of the strfry-sync configuration file.
• sync-strfry is the location of the strfry executable.
• sync-strfry-log is the location of the strfry sync command logs, it is a base filename.
• sync-status-file is the location that the sync status for each relay will be written.
• users defines the set of root pubkeys that will have their kind 3 and kind 10002 events used to define the router streams.

Other user options:

• pubkey is the hex encoding of a Nostr user's public key
• dir defines the direction of the stream. Values can be "down", "both" or "up".
• depth defines how deep the kind 3 contact/follow list will be navigated (it is usually left as 1).
• relay-depth option is the depth that relay list metadata is added to the config, it must be equal or less than the depth.

Running

To run the program:

./strfry-config --conf="</path/to/config.yml>"

This will start a daemon process that will create the configuration files necessary to run a strfry router. Please see strfry router documentation for further information about installing and running the router. The strfry router will reload modifications to the config made from this daemon automatically. Similarly the config for the plugin will also met reloaded, thus changes can be made to the topology without restarting the processes.

StrFry Sync

Build & Install

make
cp strfry-sync /usr/local/bin/strfry-sync

You can also enable a service to keep it running:

cp scripts/strfry-sync.service /etc/systemd/system/strfry-sync.service

Then edit it with the customizations and enable it with systemctl enable <name>.

This program uses the strfry sync command to synchronize a set of users defined in the configuration file. The file is auto generated by the command strfry-config based on user's pubkeys. As similar to the router, Their kind 3 (NIP-02) contact/follow lists and kind 10002 (NIP-65) relay list metadata ("outbox model") are retrieved for syncing.

Running

To run the program:

./strfry-sync --conf="</path/to/config.json>"

StrFry Down Plugin

Build & Install

make
cp strfry-down-plugin /usr/local/bin/strfry-down-plugin

This plugin is used for the strfry router and strfry relay to allow events from specific authors based on a config file auto generated by strfry-config.

Configuration

In your strfry.conf file, you can add this plugin by including it in the write policy configuration.

	writePolicy {
		plugin = "/var/local/bin/strfry-down-plugin --conf=/var/local/strfry/down-plugin.json"
	}

To configure the plugin use the strfry-config tool and point the configuration to that output file.

Documentation

Index

• Constants
• Variables
• func NegentropyUnsupportedLog(log []byte) bool
• type ConcurrentCounter
  • func (g *ConcurrentCounter) Begin()
  • func (g *ConcurrentCounter) Done()
  • func (g *ConcurrentCounter) Value() int
  • func (g *ConcurrentCounter) Wait(max int)
• type Config
• type DownPlugin
  • func NewDownPlugin() *DownPlugin
  • func (g *DownPlugin) AppendUniqueAuthor(pubkey string)
• type Filter
  • func NewFilter() *Filter
  • func (g *Filter) AppendUniqueAuthor(author string)
  • func (g *Filter) AuthorLength() int
  • func (g *Filter) MarshalJSON() ([]byte, error)
  • func (g *Filter) UnmarshalJSON(data []byte) error
• type RouterConfig
  • func (g *RouterConfig) AddUser(cfg *Config, user *User, relays []string, contacts []string)
  • func (g *RouterConfig) PluginAppendUniqueAuthor(pubkey string)
  • func (g *RouterConfig) WritePluginConfig(path string) error
• type RouterStream
  • func NewRouterStream(dir string, pluginPath string) *RouterStream
  • func (g *RouterStream) AppendUniqueRelay(relay string)
• type SyncConfig
  • func NewSyncConfig() SyncConfig
  • func (g *SyncConfig) AppendUniqueUser(user *SyncUser)
• type SyncUser
• type User

Constants

const (
	FilterMaxBytes       = 65535
	FilterMaxAuthors     = 950
	MaxConcurrentReqs    = 10
	MaxConcurrentSyncs   = 10
	DefaultRouterTimeout = "600"
)

Variables

var (
	UnsupportedMsgs = []string{
		"ERROR: negentropy error: negentropy query missing elements",
		"ERROR: bad msg: negentropy disabled",
		"ERROR: bad msg: invalid message",
		"bad message type",
		`invalid: \"value\" does not match any of the allowed types`,
		"Command unrecognized",
		"error: bad message",
		"could not parse command",
		"unknown message type NEG-OPEN",
		"ERROR: bad msg: unknown cmd",
	}

	UnexpectedReg = regexp.MustCompile("^(.*)Unexpected message from relay: \\[\"NOTICE\"\\,")
)

Functions

func NegentropyUnsupportedLog

func NegentropyUnsupportedLog(log []byte) bool

Types

type ConcurrentCounter

type ConcurrentCounter struct {
	// contains filtered or unexported fields
}

func (*ConcurrentCounter) Begin

func (g *ConcurrentCounter) Begin()

func (*ConcurrentCounter) Done

func (g *ConcurrentCounter) Done()

func (*ConcurrentCounter) Value

func (g *ConcurrentCounter) Value() int

func (*ConcurrentCounter) Wait

func (g *ConcurrentCounter) Wait(max int)

type Config

type Config struct {
	LogLevel        string   `koanf:"log-level"`
	PluginDown      string   `koanf:"plugin-down"`
	PluginConfig    string   `koanf:"plugin-config"`
	RouterTimeout   string   `koanf:"router-timeout"`
	RouterConfig    string   `koanf:"router-config"`
	SyncConfig      string   `koanf:"sync-config"`
	SyncStatusFile  string   `koanf:"sync-status-file"`
	StrFryLog       string   `koanf:"sync-strfry-log"`
	StrFryBin       string   `koanf:"sync-strfry"`
	StrFryConfig    string   `koanf:"sync-strfry-config"`
	DiscoveryRelays []string `koanf:"discovery-relays"`
	Users           []User   `koanf:"users"`
}

type DownPlugin

type DownPlugin struct {
	AuthorAllow []string `json:"author-allow"`
	// contains filtered or unexported fields
}

func NewDownPlugin

func NewDownPlugin() *DownPlugin

func (*DownPlugin) AppendUniqueAuthor

func (g *DownPlugin) AppendUniqueAuthor(pubkey string)

type Filter

type Filter struct {
	Filter *nostr.Filter
	// contains filtered or unexported fields
}

func NewFilter

func NewFilter() *Filter

func (*Filter) AppendUniqueAuthor

func (g *Filter) AppendUniqueAuthor(author string)

func (*Filter) AuthorLength

func (g *Filter) AuthorLength() int

func (*Filter) MarshalJSON

func (g *Filter) MarshalJSON() ([]byte, error)

func (*Filter) UnmarshalJSON

func (g *Filter) UnmarshalJSON(data []byte) error

type RouterConfig

type RouterConfig struct {
	Streams map[string]*RouterStream `json:"streams"`
	Timeout string                   `json:"connectionTimeout"`
	// contains filtered or unexported fields
}

func (*RouterConfig) AddUser

func (g *RouterConfig) AddUser(
	cfg *Config,
	user *User,
	relays []string,
	contacts []string)

func (*RouterConfig) PluginAppendUniqueAuthor

func (g *RouterConfig) PluginAppendUniqueAuthor(pubkey string)

func (*RouterConfig) WritePluginConfig

func (g *RouterConfig) WritePluginConfig(path string) error

type RouterStream

type RouterStream struct {
	Direction  string   `json:"dir"`
	PluginDown string   `json:"pluginDown,omitempty"`
	PluginUp   string   `json:"pluginUp,omitempty"`
	Relays     []string `json:"urls"`
	Filter     *Filter  `json:"filter,omitempty"`
	// contains filtered or unexported fields
}

func NewRouterStream

func NewRouterStream(dir string, pluginPath string) *RouterStream

func (*RouterStream) AppendUniqueRelay

func (g *RouterStream) AppendUniqueRelay(relay string)

type SyncConfig

type SyncConfig struct {
	LogLevel     string      `koanf:"log-level" json:"log-level"`
	StrFryBin    string      `koanf:"strfry-bin" json:"strfry-bin"`
	StrFryConfig string      `koanf:"strfry-config" json:"strfry-config"`
	StrFryLog    string      `koanf:"strfry-log" json:"strfry-log"`
	StatusFile   string      `koanf:"status-file" json:"status-file"`
	Users        []*SyncUser `koanf:"users" json:"users"`
	// contains filtered or unexported fields
}

func NewSyncConfig

func NewSyncConfig() SyncConfig

func (*SyncConfig) AppendUniqueUser

func (g *SyncConfig) AppendUniqueUser(user *SyncUser)

type SyncUser

type SyncUser struct {
	Direction string   `json:"dir"`
	PubKey    string   `json:"pubkey"`
	Relays    []string `json:"relays"`
}

type User

type User struct {
	Name       string `koanf:"name"`
	PubKey     string `koanf:"pubkey"`
	Depth      int    `koanf:"depth"`
	RelayDepth int    `koanf:"relay-depth"`
	Direction  string `koanf:"dir"`
}