Documentation
¶
Index ¶
- Constants
- func IsAvailable() bool
- func SetGlobalDB(db *NDB)
- type NDB
- func (db *NDB) BeginQuery() (*Txn, error)
- func (db *NDB) CheckDuplicateEvent(evt nostr.Event) (bool, error)
- func (db *NDB) Close()
- func (db *NDB) DeleteNoteByID(id [32]byte) error
- func (db *NDB) GetAllAuthors() []string
- func (db *NDB) ProcessDeletion(ctx context.Context, evt nostr.Event) error
- func (db *NDB) ProcessEvent(json string) error
- func (db *NDB) ProcessEvents(ldjson string) error
- func (db *NDB) PurgeOldEvents(cfg *cfgType.EventPurgeConfig, whitelistedPubkeys []string) int
- func (db *NDB) Query(filters []nostr.Filter, limit int) ([]nostr.Event, error)
- func (db *NDB) ScheduleEventPurging(cfg *cfgType.ServerConfig, getWhitelistedPubkeys func() []string)
- func (db *NDB) Stat() (*C.struct_ndb_stat, error)
- func (db *NDB) StoreEvent(ctx context.Context, evt nostr.Event) error
- type Txn
Constants ¶
const ( // FlagSkipNoteVerify makes the ingester skip signature verification. // Safe for imports from a trusted source (e.g. a previous grain/mongo // export) where events were already validated at original ingest time. FlagSkipNoteVerify = 1 << 1 )
NDB open flags. These map 1:1 onto nostrdb.h NDB_FLAG_* bits.
Variables ¶
This section is empty.
Functions ¶
func IsAvailable ¶
func IsAvailable() bool
IsAvailable returns true if the database is initialized and ready.
Types ¶
type NDB ¶
type NDB struct {
// contains filtered or unexported fields
}
NDB wraps a nostrdb instance. It is safe for concurrent use.
func GetDB ¶
func GetDB() *NDB
GetDB returns the global nostrdb instance. Returns nil if the database hasn't been initialized.
func Open ¶
Open initializes a new nostrdb database at the given directory path. mapSizeMB sets the maximum database size in megabytes (LMDB map size). ingestThreads controls how many threads nostrdb uses to process incoming events.
func OpenWithFlags ¶
OpenWithFlags is like Open but forwards an ndb_config_set_flags bitmask to nostrdb. Use FlagSkipNoteVerify for trusted-source bulk imports.
func (*NDB) BeginQuery ¶
BeginQuery starts a read transaction for querying the database. The caller MUST call EndQuery when done.
func (*NDB) CheckDuplicateEvent ¶
CheckDuplicateEvent checks if an event with the given ID already exists. Uses a lightweight pointer check — no deserialization needed.
func (*NDB) Close ¶
func (db *NDB) Close()
Close shuts down the nostrdb instance and frees resources.
func (*NDB) DeleteNoteByID ¶
DeleteNoteByID enqueues a real delete of an event from nostrdb by its raw 32-byte ID. The delete is applied by the nostrdb writer thread in FIFO order with ingests — a delete of an in-flight ingest of the same ID is committed atomically in the same batch and cannot race.
This is grain's one and only physical-delete primitive. All three deletion audiences (NIP-09 author deletes, operator retention / PurgeOldEvents, replaceable/addressable supersede, and admin --delete CLI) call through here. Authorization is the caller's responsibility: this function performs no checks beyond "is the DB open and is the writer queue accepting work".
Returns an error only if the DB is closed or the writer inbox is full. "Not found" is not an error at this layer — it's logged at C level and the call is a no-op.
func (*NDB) GetAllAuthors ¶
GetAllAuthors returns all unique pubkeys that have events in the database.
func (*NDB) ProcessDeletion ¶
ProcessDeletion handles NIP-09 kind 5 deletion events. It walks the event's `e` and `a` tags, enforces NIP-09's same-pubkey authorization rule at each tag, physically removes matching events via the nostrdb writer thread (ndb_request_delete_note), then stores the kind-5 record itself so clients can still see the deletion marker per spec.
Tag processing is best-effort: a failure on one tag is logged and the next tag is still processed. The kind-5 is always ingested at the end so that a client querying for it still sees it, even if none of its targets existed.
func (*NDB) ProcessEvent ¶
ProcessEvent ingests a raw JSON Nostr event string into the database. nostrdb parses the JSON, validates, indexes, and stores the event internally. The JSON should be a relay message like: ["EVENT", <subscription_id>, <event>] or just the event object itself for direct ingestion.
func (*NDB) ProcessEvents ¶
ProcessEvents ingests multiple newline-delimited JSON events.
func (*NDB) PurgeOldEvents ¶
func (db *NDB) PurgeOldEvents(cfg *cfgType.EventPurgeConfig, whitelistedPubkeys []string) int
PurgeOldEvents removes events older than the configured retention window. Whitelisted pubkeys (configured members) are excluded when ExcludeWhitelisted is set — this is the "non-member cleanup" knob that keeps member content forever while aging out drive-by events.
func (*NDB) Query ¶
Query executes NIP-01 filters against the database and returns matching events. This opens and closes a read transaction internally.
func (*NDB) ScheduleEventPurging ¶
func (db *NDB) ScheduleEventPurging(cfg *cfgType.ServerConfig, getWhitelistedPubkeys func() []string)
ScheduleEventPurging runs periodic event purging at the configured interval.
func (*NDB) Stat ¶
func (db *NDB) Stat() (*C.struct_ndb_stat, error)
Stat returns database statistics.
func (*NDB) StoreEvent ¶
StoreEvent processes and stores a Nostr event in the database. nostrdb handles event ingestion internally including parsing and indexing. For replaceable and addressable events, we must handle the replacement semantics ourselves since nostrdb does not enforce NIP-01 replacement rules.
type Txn ¶
type Txn struct {
// contains filtered or unexported fields
}
Txn represents a read transaction against nostrdb. Transactions must be short-lived to avoid blocking LMDB space reclamation.
func (*Txn) EndQuery ¶
func (txn *Txn) EndQuery()
EndQuery ends a read transaction. Must be called after BeginQuery.
func (*Txn) GetNoteByID ¶
GetNoteByID looks up a single event by its hex ID.
Source Files