relay29

README

= relay29 image:https://pkg.go.dev/badge/github.com/fiatjaf/relay29.svg[link=https://pkg.go.dev/github.com/fiatjaf/relay29]

A library for creating NIP-29 relays, works with https://github.com/fiatjaf/khatru[khatru] using the https://pkg.go.dev/github.com/fiatjaf/relay29/khatru29[khatru29] wrapper.

CAUTION: This is probably broken so please don't trust it for anything serious and be prepared to delete your database.

[source,go]
----
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/fiatjaf/eventstore/slicestore"
	"github.com/fiatjaf/khatru/policies"
	"github.com/fiatjaf/relay29"
	"github.com/fiatjaf/relay29/khatru29"
	"github.com/nbd-wtf/go-nostr"
)

func main() {
	relayPrivateKey := nostr.GeneratePrivateKey()

	db := &slicestore.SliceStore{} // this only keeps things in memory, use a different eventstore in production
	db.Init()

	relay, _ := khatru29.Init(relay29.Options{
		Domain:    "localhost:2929",
		DB:        db,
		SecretKey: relayPrivateKey,
	})

	// init relay
	relay.Info.Name = "very ephemeral chat relay"
	relay.Info.Description = "everything will be deleted as soon as I turn off my computer"

	// extra policies
	relay.RejectEvent = append(relay.RejectEvent,
		policies.PreventLargeTags(64),
		policies.PreventTooManyIndexableTags(6, []int{9005}, nil),
		policies.RestrictToSpecifiedKinds(
			9, 10, 11, 12,
			30023, 31922, 31923, 9802,
			9000, 9001, 9002, 9003, 9004, 9005, 9006, 9007,
			9021,
		),
		policies.PreventTimestampsInThePast(60),
		policies.PreventTimestampsInTheFuture(30),
	)

	// http routes
	relay.Router().HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "nothing to see here, you must use a nip-29 powered client")
	})

	fmt.Println("running on http://0.0.0.0:2929")
	if err := http.ListenAndServe(":2929", relay); err != nil {
		log.Fatal("failed to serve")
	}
}
----

== How to use

Basically you just call `khatru29.Init()` and then you get back a `khatru.Relay` and a `relay29.State` instances. The state has inside it also a map of `Group` objects that you can read but you should not modify manually. To modify these groups you must write moderation events with the `.AddEvent()` method of the `Relay`. This API may be improved later.

See link:examples/groups.fiatjaf.com/main.go[] for a (not very much) more complex example.

== How it works

What this library does is basically:
- it keeps a list of of groups with metadata in memory (not the messages);
- it checks a bunch of stuff for every event and filter received;
- it acts on moderation events and on join-request events received and modify the group state;
- it generates group metadata events (39000, 39001, 39002) events on the fly (these are not stored) and returns them to whoever queries them;
- on startup it loads all the moderation events (9000, 9001, etc) from the database and rebuilds the group state from that (so if you want to modify the group state permanently you must publish one of these events to the relay — but of course you can also monkey-patch the map of groups in memory like an animal if you want);

Documentation

Index

• func GetGroupIDFromEvent(event *nostr.Event) string
• type Group
• type Options
• type State
  • func New(opts Options) *State
  • func (s *State) AdminsQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)
  • func (s *State) ApplyModerationAction(ctx context.Context, event *nostr.Event)
  • func (s *State) GetGroupFromEvent(event *nostr.Event) *Group
  • func (s *State) MembersQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)
  • func (s *State) MetadataQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)
  • func (s *State) NewGroup(id string) *Group
  • func (s *State) NormalEventQuery(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)
  • func (s *State) PreventWritingOfEventsJustDeleted(ctx context.Context, event *nostr.Event) (reject bool, msg string)
  • func (s *State) ReactToJoinRequest(ctx context.Context, event *nostr.Event)
  • func (s *State) RequireHTagForExistingGroup(ctx context.Context, event *nostr.Event) (reject bool, msg string)
  • func (s *State) RequireKindAndSingleGroupIDOrSpecificEventReference(ctx context.Context, filter nostr.Filter) (reject bool, msg string)
  • func (s *State) RequireModerationEventsToBeRecent(ctx context.Context, event *nostr.Event) (reject bool, msg string)
  • func (s *State) RestrictInvalidModerationActions(ctx context.Context, event *nostr.Event) (reject bool, msg string)
  • func (s *State) RestrictWritesBasedOnGroupRules(ctx context.Context, event *nostr.Event) (reject bool, msg string)

Functions

func GetGroupIDFromEvent

func GetGroupIDFromEvent(event *nostr.Event) string

Types

type Group

type Group struct {
	nip29.Group
	// contains filtered or unexported fields
}

type Options

type Options struct {
	Domain    string
	DB        eventstore.Store
	SecretKey string
}

type State

type State struct {
	Domain string
	Groups *xsync.MapOf[string, *Group]
	DB     eventstore.Store
	Relay  interface {
		BroadcastEvent(*nostr.Event)
		AddEvent(context.Context, *nostr.Event) (skipBroadcast bool, writeError error)
	}
	GetAuthed func(context.Context) string
	// contains filtered or unexported fields
}

func New

func New(opts Options) *State

func (*State) AdminsQueryHandler

func (s *State) AdminsQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)

func (*State) ApplyModerationAction

func (s *State) ApplyModerationAction(ctx context.Context, event *nostr.Event)

func (*State) GetGroupFromEvent

func (s *State) GetGroupFromEvent(event *nostr.Event) *Group

func (*State) MembersQueryHandler

func (s *State) MembersQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)

func (*State) MetadataQueryHandler

func (s *State) MetadataQueryHandler(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)

func (*State) NewGroup

func (s *State) NewGroup(id string) *Group

func (*State) NormalEventQuery

func (s *State) NormalEventQuery(ctx context.Context, filter nostr.Filter) (chan *nostr.Event, error)

func (*State) PreventWritingOfEventsJustDeleted

func (s *State) PreventWritingOfEventsJustDeleted(ctx context.Context, event *nostr.Event) (reject bool, msg string)

func (*State) ReactToJoinRequest

func (s *State) ReactToJoinRequest(ctx context.Context, event *nostr.Event)

func (*State) RequireHTagForExistingGroup

func (s *State) RequireHTagForExistingGroup(ctx context.Context, event *nostr.Event) (reject bool, msg string)

func (*State) RequireKindAndSingleGroupIDOrSpecificEventReference

func (s *State) RequireKindAndSingleGroupIDOrSpecificEventReference(ctx context.Context, filter nostr.Filter) (reject bool, msg string)

func (*State) RequireModerationEventsToBeRecent

func (s *State) RequireModerationEventsToBeRecent(ctx context.Context, event *nostr.Event) (reject bool, msg string)

func (*State) RestrictInvalidModerationActions

func (s *State) RestrictInvalidModerationActions(ctx context.Context, event *nostr.Event) (reject bool, msg string)

func (*State) RestrictWritesBasedOnGroupRules

func (s *State) RestrictWritesBasedOnGroupRules(ctx context.Context, event *nostr.Event) (reject bool, msg string)