strfrui.go

// Package strfrui provides foundations for building [strfry's event-sifters plugins] in Go.
//
// If you want to explore built-in event-sifter implementations and combinators,
// which can be used to make complex sifter logics from small parts,
// see the doc of [github.com/jiftechnify/strfrui/sifters] package.
//
// [strfry's event-sifters plugins]: https://github.com/hoytech/strfry/blob/master/docs/plugins.md
package strfrui

import (
	"bufio"
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/nbd-wtf/go-nostr"
)

// SourceType represents a source type of a Nostr event, in other words, where an event came from.
type SourceType string

const (
	// SourceTypeIP4 shows that an event was sent from a client which has an IPv4 address.
	SourceTypeIP4 SourceType = "IP4"

	// SourceTypeIP6 shows that an event was sent from a client which has an IPv6 address.
	SourceTypeIP6 SourceType = "IP6"

	// SourceTypeImport shows that an event was imported via "strfry import" command.
	SourceTypeImport SourceType = "Import"

	// SourceTypeStream shows that an event was imported from another relay via "strfry stream" or "strfry router" command.
	SourceTypeStream SourceType = "Stream"

	// SourceTypeSync shows that an event was imported from another relay via "strfry sync" command.
	SourceTypeSync SourceType = "Sync"
)

// IsEndUser checks whether the source is an "end-user" (or, a "user-facing client").
func (st SourceType) IsEndUser() bool {
	switch st {
	case SourceTypeIP4, SourceTypeIP6:
		return true
	default:
		return false
	}
}

// Action represents a type of action by event sifter, in other words, how to process an event.
type Action string

const (
	ActionAccept       Action = "accept"
	ActionReject       Action = "reject"
	ActionShadowReject Action = "shadowReject"
)

// Input is a data structure of event sifter's input.
type Input struct {
	// A type of input. As of strfry 0.9.6, it is always "new".
	Type string `json:"type"`

	// An event data sent by a client or imported from file / another relay.
	Event *nostr.Event `json:"event"`

	// Unix timestamp (in second) of when the event was received by the relay.
	ReceivedAt uint64 `json:"receivedAt"`

	// The source type, or where the event came from.
	SourceType SourceType `json:"sourceType"`

	// Information about event source. If SourceType is...
	//
	//   - SourceTypeIP4 or SourceTypeIP6, it's a string representation of client's IP address.
	//   - SourceTypeStream or SourceTypeSync, it's a URL of a source relay.
	//   - SourceTypeImport, it's an empty string.
	SourceInfo string `json:"sourceInfo"`
}

// Result is a data structure of event sifter's output.
// It can be generated from methods of an Input.
type Result struct {
	// The ID of the target event, taken from the ID field of Input.
	ID string `json:"id"`

	// An action to take on the target event.
	Action Action `json:"action"`

	// A message to be sent to a client (included in an OK message) if event is rejected.
	Msg string `json:"msg"`
}

// Accept accepts the event in the input.
func (i *Input) Accept() (*Result, error) {
	return &Result{
		ID:     i.Event.ID,
		Action: ActionAccept,
	}, nil
}

// Reject rejects the event in the input with a rejection message to the client.
//
// As per [NIP-01], the message should be prefixed with a machine-readable word followed by ":" (e.g. "blocked: you are not allowed to write events").
// You can use [BuildRejectMessage] to build a rejection message in that format.
//
// [NIP-01]: https://github.com/nostr-protocol/nips/blob/master/01.md
func (i *Input) Reject(msg string) (*Result, error) {
	return &Result{
		ID:     i.Event.ID,
		Action: ActionReject,
		Msg:    msg,
	}, nil
}

// ShadowReject silently rejects the event in the input, that is, makes it look accepted to the client, but actually reject it.
func (i *Input) ShadowReject() (*Result, error) {
	return &Result{
		ID:     i.Event.ID,
		Action: ActionShadowReject,
	}, nil
}

// "Machine-readable prefixes" for rejection messages. Use them with [BuildRejectMessage].
const (
	RejectReasonPrefixBlocked     = "blocked"
	RejectReasonPrefixRateLimited = "rate-limited"
	RejectReasonPrefixInvalid     = "invalid"
	RejectReasonPrefixPoW         = "pow"
	RejectReasonPrefixError       = "error"
)

// BuildRejectMessage builds a rejection message with a machine-readable prefix.
//
// The message format is defined in [NIP-01].
//
// [NIP-01]: https://github.com/nostr-protocol/nips/blob/master/01.md#from-relay-to-client-sending-events-and-notices
func BuildRejectMessage(prefix string, body string) string {
	return prefix + ": " + body
}

// A Sifter decides whether accept or reject an event based on Input, the event data itself with context information.
//
// Sift should return either Result with an action to take on the event, or error if it couldn't process the input.
// If error is returned from Sift, the event is rejected by default.
type Sifter interface {
	Sift(input *Input) (*Result, error)
}

// SifterFunc is an adapter to allow the use of functions which takes a sifter Input and returns a sifter Result as a Sifter.
type SifterFunc func(input *Input) (*Result, error)

func (s SifterFunc) Sift(input *Input) (*Result, error) {
	return s(input)
}

// Runner implements the main routine of a event sifter as Run() method.
// You may want to use [strfrui.New] to initialize a Runner and set a Sifter at the same time.
//
// The zero value for Runner is a valid Runner that accepts all events.
type Runner struct {
	sifter Sifter
}

var acceptAll = SifterFunc(func(input *Input) (*Result, error) {
	return input.Accept()
})

// Run executes the main routine of a event sifter.
func (r *Runner) Run() {
	var (
		scanner   = bufio.NewScanner(os.Stdin)
		bufStdout = bufio.NewWriter(os.Stdout)
		jsonEnc   = json.NewEncoder(bufStdout)
	)

	var processInput = func(input *Input) (*Result, error) {
		if input.Type != "new" {
			return nil, fmt.Errorf("unexpected input type: %s", input.Type)
		}

		sifter := r.sifter
		if sifter == nil {
			sifter = acceptAll
		}
		return sifter.Sift(input)
	}

	for scanner.Scan() {
		var input Input
		if err := json.Unmarshal(scanner.Bytes(), &input); err != nil {
			log.Printf("failed to parse input: %v", err)

			// write malformed output in order to reject event
			_ = jsonEnc.Encode(Result{ID: ""})
			bufStdout.Flush()
			continue
		}

		res, err := processInput(&input)
		if err != nil {
			log.Println(err)

			// reject the event by default if sifter returns error
			res, _ = input.Reject("error: event sifter failed to process input")
		}

		if err := jsonEnc.Encode(res); err != nil {
			log.Printf("failed to encode event sifter result to JSON: %v", err)
		}
		bufStdout.Flush()
	}
}

// New initializes a new Runner and set the passed Sifter at the same time.
func New(s Sifter) *Runner {
	return &Runner{
		sifter: s,
	}
}

// NewWithSifterFunc initializes a new Runner and set the passed event sifting function as a Sifter at the same time.
func NewWithSifterFunc(sf func(input *Input) (*Result, error)) *Runner {
	return &Runner{
		sifter: SifterFunc(sf),
	}
}

// SiftWith replaces the Sifter in the Runner with the passed one.
func (r *Runner) SiftWith(s Sifter) {
	r.sifter = s
}

// SiftWithFunc replaces the Sifter in the Runner with the passed event sifting function.
func (r *Runner) SiftWithFunc(sf func(input *Input) (*Result, error)) {
	r.sifter = SifterFunc(sf)
}