mongodb

README

mongodb

Package mongodb is a history Store backed by MongoDB via the official mongo- driver v2. Each message is a document in the configured collection: { "_id": ObjectId(...), // assigned by the driver "conversation_id": "u-42", "seq": 1716210000000123456, "message": "", // canonical chat.Message wire shape "created_at": ISODate(...), } Documents are read by (seq, _id). A store-local sequence generator reserves one contiguous range per Write and remains monotonic across local clock regression. Concurrent calls and writes from distinct Store instances have no defined relative order. Example: col := client.Database("scope").Collection("chat_history") store, _ := mongodb.NewStore(ctx, mongodb.StoreConfig{ Collection: col, InitializeSchema: true, // create the conversation_id index })

Install

go get github.com/Tangerg/scope/historystores/mongodb

Constructors

Every constructor validates its config and returns a value implementing the store capabilities in core/history:

• NewStore

Testing

This module integrates a third-party service, so its tests cover what runs without live credentials: config validation, request and response mapping, and error classification. The shared conformance contract is core/history/storetest — this module runs it rather than copying it.

An integration probe skips unless its credential environment variable is set, so go test ./... is always runnable offline.

Boundaries

This is an independent leaf module: it carries only its own SDK dependency and never imports a sibling provider. The shared contract every module in this family obeys is in ../ARCHITECTURE.md.

See ARCHITECTURE.md for what this module owns.

Documentation

Overview

Package mongodb is a history Store backed by MongoDB via the official mongo-driver v2.

Each message is a document in the configured collection:

{
    "_id":             ObjectId(...),     // assigned by the driver
    "conversation_id": "u-42",
    "seq":             1716210000000123456,
    "message":         "<json>",          // canonical chat.Message wire shape
    "created_at":      ISODate(...),
}

Documents are read by (`seq`, `_id`). A store-local sequence generator reserves one contiguous range per Write and remains monotonic across local clock regression. Concurrent calls and writes from distinct Store instances have no defined relative order.

Example:

col := client.Database("scope").Collection("chat_history")
store, _ := mongodb.NewStore(ctx, mongodb.StoreConfig{
    Collection:       col,
    InitializeSchema: true, // create the conversation_id index
})

Index

• type Store
  • func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
  • func (s *Store) Clear(ctx context.Context, conversationID history.ConversationID) (err error)
  • func (s *Store) Conversations(ctx context.Context) (ids []history.ConversationID, err error)
  • func (s *Store) Read(ctx context.Context, conversationID history.ConversationID) (storedMessages []chat.Message, err error)
  • func (s *Store) Write(ctx context.Context, conversationID history.ConversationID, ...) (err error)
• type StoreConfig
  • func (s StoreConfig) Validate() error

Types

type Store

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

Store persists messages as independently addressable MongoDB documents through a caller-owned collection. A local monotonic sequence and ObjectID provide deterministic read order; ordering across separate Store values remains unspecified.

func NewStore

func NewStore(ctx context.Context, config StoreConfig) (*Store, error)

func (*Store) Clear

func (s *Store) Clear(ctx context.Context, conversationID history.ConversationID) (err error)

Clear drops every document for conversationID. Unknown ids result in a no-op (DeleteMany matches zero docs).

func (*Store) Conversations

func (s *Store) Conversations(ctx context.Context) (ids []history.ConversationID, err error)

Conversations returns distinct conversation IDs in lexical order. It is a deliberate cross-conversation scan for operational tasks.

func (*Store) Read

func (s *Store) Read(ctx context.Context, conversationID history.ConversationID) (storedMessages []chat.Message, err error)

Read returns every message stored under conversationID in insertion order.

func (*Store) Write

func (s *Store) Write(ctx context.Context, conversationID history.ConversationID, messages ...chat.Message) (err error)

Write inserts every message under conversationID via InsertMany. A reserved sequence range preserves argument order and remains monotonic if the local clock moves backward.

type StoreConfig

type StoreConfig struct {
	// Collection is the live MongoDB collection. Required. The store
	// does not take ownership of the underlying client.
	Collection *mongo.Collection

	// InitializeSchema, when true, ensures an index on
	// (conversation_id, seq, _id) exists. Idempotent.
	InitializeSchema bool
}

func (StoreConfig) Validate

func (s StoreConfig) Validate() error