heartwood

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 22, 2026 License: MIT Imports: 10 Imported by: 0

README

Go-Heartwood - Nostr Event Storage for Neo4j

Source: https://git.wisehodl.dev/jay/go-heartwood

Mirror: https://github.com/wisehodl/go-heartwood

This library is in active development and not yet ready for use.

go-heartwood is a Neo4j-based event storage layer for Nostr events. It stores events as nodes in a graph and foreign-key references as relationships.

Installation

Add go-heartwood to your project:

go get git.wisehodl.dev/jay/go-heartwood

If the primary repository is unavailable, use the replace directive in your go.mod file to get the package from the github mirror:

replace git.wisehodl.dev/jay/go-heartwood => github.com/wisehodl/go-heartwood latest

Usage

Further usage examples will be added as the API stabilizes.

Writing Events
package main

import (
	"context"
	"log"
	"time"

	"git.wisehodl.dev/jay/go-roots/events"
	"git.wisehodl.dev/jay/go-roots/keys"
	"git.wisehodl.dev/jay/go-heartwood"

	"github.com/boltdb/bolt"
)

func main() {
	ctx := context.Background()

	// Connect to Neo4j
	driver, err := heartwood.ConnectNeo4j(ctx, "bolt://localhost:7687", "neo4j", "password")
	if err != nil {
		log.Fatal(err)
	}
	defer driver.Close(ctx)

	// Ensure the necessary indexes and constraints exist
	if err := heartwood.SetNeo4jSchema(ctx, driver); err != nil {
		log.Fatal(err)
	}

	// Open BoltDB
	boltdb, err := bolt.Open("events.db", 0600, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer boltdb.Close()

	// Build and validate an event using go-roots
	sk, _ := keys.GeneratePrivateKey()
	pk, _ := keys.GetPublicKey(sk)

	event := events.NewEvent(
		events.WithPubKey(pk),
		events.WithCreatedAt(time.Now().Unix()),
		events.WithKind(1),
		events.WithContent("hello from heartwood"),
	)
	event.ID = events.GetID(event)
	sig, err := events.SignEvent(event.ID, sk)
	if err != nil {
		log.Fatal(err)
	}
	event.Sig = sig

	validated, err := events.NewValidatedEvent(event)
	if err != nil {
		log.Fatal(err)
	}

	// Write events
	report := heartwood.WriteEvents(
		[]events.ValidatedEvent{validated},
		driver, boltdb,
		nil, // default WriteOptions
	)
	if report.Error != nil {
		log.Fatal(report.Error)
	}

	log.Printf("created: %d, excluded: %d, duration: %s",
		report.CreatedEventCount,
		len(report.ExcludedEvents),
		report.Duration,
	)
}

Testing

go test ./...

Documentation

Index

Constants

View Source
const BucketName string = "events"

Variables

View Source
var ErrDuplicate = errors.New("event already exists")

Functions

func BatchCheckEventsExist

func BatchCheckEventsExist(boltdb *bolt.DB, eventIDs []string) map[string]bool

func BatchWriteEvents

func BatchWriteEvents(boltdb *bolt.DB, events []EventBlob) error

func ConnectNeo4j

func ConnectNeo4j(ctx context.Context, uri, user, password string) (neo4j.Driver, error)

func ExpandReplaceableEvents

func ExpandReplaceableEvents(e roots.ValidatedEvent, s *EventSubgraph)

func ExpandTaggedEvents

func ExpandTaggedEvents(e roots.ValidatedEvent, s *EventSubgraph)

func ExpandTaggedUsers

func ExpandTaggedUsers(e roots.ValidatedEvent, s *EventSubgraph)

func IsValidTag

func IsValidTag(t roots.Tag) bool

func MergeNodes

func MergeNodes(
	ctx context.Context,
	tx neo4j.ManagedTransaction,
	batch NodeBatch,
) (neo4j.ResultSummary, error)

func MergeRels

func MergeRels(
	ctx context.Context,
	tx neo4j.ManagedTransaction,
	batch RelBatch,
) (neo4j.ResultSummary, error)

func MergeSubgraph

func MergeSubgraph(
	ctx context.Context,
	driver neo4j.Driver,
	subgraph *BatchSubgraph,
) ([]neo4j.ResultSummary, error)

func SetNeo4jSchema

func SetNeo4jSchema(ctx context.Context, driver neo4j.Driver) error

SetNeo4jSchema ensures that the necessary indexes and constraints exist in the database

func SetupBoltDB

func SetupBoltDB(boltdb *bolt.DB) error

func ToCypherLabel

func ToCypherLabel(label string) string

ToCypherLabel converts a node label or relationship type into its Cypher format.

func ToCypherLabels

func ToCypherLabels(labels []string) string

ToCypherLabels converts a list of node labels into its Cypher format.

func ToCypherProps

func ToCypherProps(keys []string, prefix string) string

Types

type BatchSubgraph

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

func NewBatchSubgraph

func NewBatchSubgraph(matchProvider MatchKeysProvider) *BatchSubgraph

func (*BatchSubgraph) AddNode

func (s *BatchSubgraph) AddNode(node *Node) error

func (*BatchSubgraph) AddRel

func (s *BatchSubgraph) AddRel(rel *Relationship) error

func (*BatchSubgraph) NodeBatches

func (s *BatchSubgraph) NodeBatches() ([]NodeBatch, error)

func (*BatchSubgraph) NodeCount

func (s *BatchSubgraph) NodeCount() int

func (*BatchSubgraph) RelBatches

func (s *BatchSubgraph) RelBatches() ([]RelBatch, error)

func (*BatchSubgraph) RelCount

func (s *BatchSubgraph) RelCount() int

type EventBlob

type EventBlob struct {
	ID   []byte
	JSON []byte
}

type EventSubgraph

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

func NewEventSubgraph

func NewEventSubgraph() *EventSubgraph

func (*EventSubgraph) AddNode

func (s *EventSubgraph) AddNode(node *Node)

func (*EventSubgraph) AddRel

func (s *EventSubgraph) AddRel(rel *Relationship)

func (*EventSubgraph) FirstNodeByLabel

func (s *EventSubgraph) FirstNodeByLabel(label string) *Node

func (*EventSubgraph) Nodes

func (s *EventSubgraph) Nodes() []*Node

func (*EventSubgraph) NodesByLabel

func (s *EventSubgraph) NodesByLabel(label string) []*Node

func (*EventSubgraph) Rels

func (s *EventSubgraph) Rels() []*Relationship

type ExcludedEvent

type ExcludedEvent struct {
	Event  roots.ValidatedEvent
	Reason error
}

type Expander

type Expander func(e roots.ValidatedEvent, s *EventSubgraph)

func DefaultExpanders

func DefaultExpanders() []Expander

type ExpanderPipeline

type ExpanderPipeline []Expander

func NewExpanderPipeline

func NewExpanderPipeline(expanders ...Expander) ExpanderPipeline

type MatchKeysProvider

type MatchKeysProvider interface {
	// GetLabels returns the array of node labels in the mapping.
	GetLabels() []string

	// GetKeys returns the node property keys used to match nodes with the
	// given label and a boolean indicating the success of the lookup.
	GetKeys(label string) ([]string, bool)
}

MatchKeysProvider defines methods for querying a mapping of node labels and the property keys used to match nodes with them.

type Node

type Node struct {
	// Set of labels on the node.
	Labels *StringSet
	// Mapping of properties on the node.
	Props Properties
}

Node represents a Neo4j node entity, encapsulating its labels and properties.

func NewEventNode

func NewEventNode(id string) *Node

func NewNode

func NewNode(label string, props Properties) *Node

NewNode creates a new node with the given label and properties.

func NewRelayNode

func NewRelayNode(url string) *Node

func NewReplacementKeyNode

func NewReplacementKeyNode(pubkey string, kind int) *Node

func NewTagNode

func NewTagNode(name string, value string) *Node

func NewUserNode

func NewUserNode(pubkey string) *Node

func (*Node) MatchProps

func (n *Node) MatchProps(
	matchProvider MatchKeysProvider) (string, Properties, error)

MatchProps returns the node label and the property values to match it in the database.

func (*Node) Serialize

func (n *Node) Serialize() *SerializedNode

type NodeBatch

type NodeBatch struct {
	MatchLabel string
	Labels     []string
	MatchKeys  []string
	Nodes      []*Node
}

type Properties

type Properties map[string]any

Properties represents a map of node or relationship props.

type RelBatch

type RelBatch struct {
	Type           string
	StartLabel     string
	StartMatchKeys []string
	EndLabel       string
	EndMatchKeys   []string
	Rels           []*Relationship
}

type Relationship

type Relationship struct {
	// The relationship type.
	Type string
	// The start node for the relationship.
	Start *Node
	// The end node for the relationship.
	End *Node
	// Mapping of properties on the relationship
	Props Properties
}

Relationship represents a Neo4j relationship between two nodes, including its type and properties.

func NewForUserRel

func NewForUserRel(
	start *Node, end *Node, props Properties) *Relationship

func NewIsReplaceableRel

func NewIsReplaceableRel(
	start *Node, end *Node, props Properties) *Relationship

func NewReferencesEventRel

func NewReferencesEventRel(
	start *Node, end *Node, props Properties) *Relationship

func NewReferencesReplacementKeyRel

func NewReferencesReplacementKeyRel(
	start *Node, end *Node, props Properties) *Relationship

func NewReferencesUserRel

func NewReferencesUserRel(
	start *Node, end *Node, props Properties) *Relationship

func NewRelationship

func NewRelationship(
	rtype string, start *Node, end *Node, props Properties) *Relationship

NewRelationship creates a new relationship with the given type, start node, end node, and properties

func NewRelationshipWithValidation

func NewRelationshipWithValidation(
	rtype string,
	startLabel string,
	endLabel string,
	start *Node,
	end *Node,
	props Properties) *Relationship

func NewSignedRel

func NewSignedRel(
	start *Node, end *Node, props Properties) *Relationship

func NewTaggedRel

func NewTaggedRel(
	start *Node, end *Node, props Properties) *Relationship

func NewWithDTagRel

func NewWithDTagRel(
	start *Node, end *Node, props Properties) *Relationship

func (*Relationship) Serialize

func (r *Relationship) Serialize() *SerializedRel

type SerializedNode

type SerializedNode = Properties

type SerializedRel

type SerializedRel = map[string]Properties

type SimpleMatchKeys

type SimpleMatchKeys struct {
	Keys map[string][]string
}

SimpleMatchKeys is a simple implementation of the MatchKeysProvider interface.

func NewSimpleMatchKeys

func NewSimpleMatchKeys() *SimpleMatchKeys

func (*SimpleMatchKeys) GetKeys

func (p *SimpleMatchKeys) GetKeys(label string) ([]string, bool)

func (*SimpleMatchKeys) GetLabels

func (p *SimpleMatchKeys) GetLabels() []string

type StringSet

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

func NewStringSet

func NewStringSet(items ...string) *StringSet

func (*StringSet) Add

func (s *StringSet) Add(item string)

func (*StringSet) AsSortedArray

func (s *StringSet) AsSortedArray() []string

func (*StringSet) Contains

func (s *StringSet) Contains(item string) bool

func (*StringSet) Equal

func (s *StringSet) Equal(other StringSet) bool

func (*StringSet) Length

func (s *StringSet) Length() int

func (*StringSet) Remove

func (s *StringSet) Remove(item string)

type WriteOptions

type WriteOptions struct {
	Expanders         ExpanderPipeline
	BoltReadBatchSize int
}

type WriteReport

type WriteReport struct {
	ExcludedEvents       []ExcludedEvent
	CreatedEventCount    int
	Neo4jResultSummaries []neo4j.ResultSummary
	Duration             time.Duration
	Error                error
}

func WriteEvents

func WriteEvents(
	events []roots.ValidatedEvent,
	driver neo4j.Driver, boltdb *bolt.DB,
	opts *WriteOptions,
) WriteReport

type WriteResult

type WriteResult struct {
	ResultSummaries []neo4j.ResultSummary
	Error           error
}

Directories

Path Synopsis
cmd
gen-fixtures command
gen-fixtures generates cryptographically valid Nostr test events and writes them to testdata/events.json.
gen-fixtures generates cryptographically valid Nostr test events and writes them to testdata/events.json.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址