cassandra

README

cassandra

Package cassandra is a history Store backed by Apache Cassandra via gocql. Schema (created by InitializeSchema=true): CREATE TABLE .

( conversation_id TEXT, seq TIMEUUID, message TEXT, PRIMARY KEY ((conversation_id), seq) ) WITH CLUSTERING ORDER BY (seq ASC); conversation_id is the partition key and seq is a client-generated TIMEUUID clustering key. Each Write reserves a strictly increasing local sequence range and sends one unlogged batch to that partition. Concurrent calls and writes from distinct Store instances have no defined relative order. Example: cluster := gocql.NewCluster("127.0.0.1") cluster.Keyspace = "scope" sess, _ := cluster.CreateSession() defer sess.Close() store, _ := cassandra.NewStore(ctx, cassandra.StoreConfig{ Session: sess, Keyspace: "scope", InitializeSchema: true, })

Install

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

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 cassandra is a history Store backed by Apache Cassandra via gocql.

Schema (created by InitializeSchema=true):

CREATE TABLE <keyspace>.<table> (
    conversation_id TEXT,
    seq             TIMEUUID,
    message         TEXT,
    PRIMARY KEY ((conversation_id), seq)
) WITH CLUSTERING ORDER BY (seq ASC);

`conversation_id` is the partition key and `seq` is a client-generated TIMEUUID clustering key. Each Write reserves a strictly increasing local sequence range and sends one unlogged batch to that partition. Concurrent calls and writes from distinct Store instances have no defined relative order.

Example:

cluster := gocql.NewCluster("127.0.0.1")
cluster.Keyspace = "scope"
sess, _ := cluster.CreateSession()
defer sess.Close()

store, _ := cassandra.NewStore(ctx, cassandra.StoreConfig{
    Session:          sess,
    Keyspace:         "scope",
    InitializeSchema: true,
})

Index

• Constants
• 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

Constants

const (
	DefaultKeyspace  = "scope"
	DefaultTableName = "chat_history"
)

Types

type Store

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

Store persists each conversation in one Cassandra partition through a caller-owned session. It never closes that session. A Write preserves its argument order with a locally monotonic TIMEUUID range; relative ordering across concurrent calls or 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 row for conversationID. Unknown ids are a no-op.

func (*Store) Conversations

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

Conversations returns every stored conversation ID in lexical order.

SELECT DISTINCT on the partition key reads only partition metadata, so no ALLOW FILTERING is needed.

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 (TIMEUUID ascending).

func (*Store) Write

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

Write appends every message under conversationID in one single-partition unlogged batch. Client-generated TIMEUUIDs are strictly increasing within one call; concurrent calls have no defined relative order.

type StoreConfig

type StoreConfig struct {
	// Session is the live gocql session. Required. Callers own
	// session lifetime.
	Session *gocql.Session

	// Keyspace is the CQL keyspace. Optional: defaults to
	// [DefaultKeyspace]. The keyspace must already exist (Cassandra
	// keyspace creation needs replication-strategy choices the store
	// cannot make on the user's behalf).
	Keyspace string

	// TableName is the CQL table. Optional: defaults to
	// [DefaultTableName] ("chat_history").
	TableName string

	// InitializeSchema, when true, creates the table if it doesn't
	// already exist. The keyspace itself is NOT created.
	InitializeSchema bool
}

func (StoreConfig) Validate

func (s StoreConfig) Validate() error