botsfwstoredalgo

README

bots-fw-store-dalgo

The default DALgo adapter for bots-fw-store/botsfwstore.StateStore.

It keeps the established keys and record shapes unchanged:

botPlatforms/{platform}/botUsers/{platformUser} and botPlatforms/{platform}/bots/{bot}/botChats/{chat}.

Consequently, adopting this module is a code-composition change, not a database migration. Provide an AppUserStore that knows how the consuming application creates and loads its own users. Its PrepareAppUser phase may idempotently provision external identity before the retryable callback; its EnsureAppUser phase persists the prepared application record with the supplied transaction. The adapter commits that record, the platform-user link, and chat together. The framework itself never sees a DALgo connection or transaction.

Documentation

Overview

Package botsfwstoredalgo is the DALgo implementation of botsfwstore.StateStore.

It deliberately retains the historical botPlatforms/bots/botUsers/botChats key layout, so moving to this adapter requires no data migration.

Index

• func CreatePlatformUserRecord(ctx context.Context, tx dal.ReadwriteTransaction, platformID, userID string, ...) error
• func NewBotChatKey[PlatformID ~string](platformID PlatformID, botID, chatID string) *dalrecord.Key
• func NewBotKey[PlatformID ~string](platformID PlatformID, botID string) *dalrecord.Key
• func NewPlatformKey[PlatformID ~string](platformID PlatformID) *dalrecord.Key
• func NewPlatformUserKey[PlatformID ~string](platformID PlatformID, userID string) *dalrecord.Key
• func NewWebhookUpdateKey(key botsfwstore.WebhookUpdateKey) *dalrecord.Key
• type AppUserStore
• type BotUser
• type DBProvider
• type PlatformUserRecord
  • func GetPlatformUser(ctx context.Context, reader dal.ReadSession, platformID, userID string, ...) (PlatformUserRecord, error)
• type StateStore
  • func NewStateStore(db dal.DB, appUsers AppUserStore, opts ...StateStoreOption) *StateStore
  • func NewStateStoreWithProvider(getDB DBProvider, appUsers AppUserStore, opts ...StateStoreOption) *StateStore
  • func (s *StateStore) AppUser(ctx context.Context, botID, appUserID string) (result botsfwstore.AppUser, err error)
  • func (s *StateStore) ClaimWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseUntil time.Time) (claim botsfwstore.WebhookUpdateClaim, err error)
  • func (s *StateStore) CompleteWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseID string) error
  • func (s *StateStore) EnsureLinked(ctx context.Context, request botsfwstore.LinkRequest) (linked botsfwstore.LinkedIdentity, err error)
  • func (s *StateStore) FailWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseID string, ...) error
  • func (s *StateStore) PlatformUser(ctx context.Context, identity botsfwstore.Identity, ...) (result botsfwstore.PlatformUser, err error)
  • func (s *StateStore) SaveChat(ctx context.Context, identity botsfwstore.Identity, ...) error
  • func (s *StateStore) SetPlatformUserAccessGranted(ctx context.Context, identity botsfwstore.Identity, ...) (result botsfwstore.PlatformUser, err error)
• type StateStoreOption
  • func WithClock(now func() time.Time) StateStoreOption

Functions

func CreatePlatformUserRecord

func CreatePlatformUserRecord(ctx context.Context, tx dal.ReadwriteTransaction, platformID, userID string, data botsfwmodels.PlatformUserData) error

CreatePlatformUserRecord inserts a platform user in the historical schema.

func NewBotChatKey

func NewBotChatKey[PlatformID ~string](platformID PlatformID, botID, chatID string) *dalrecord.Key

NewBotChatKey creates the historical bot-chat key.

func NewBotKey

func NewBotKey[PlatformID ~string](platformID PlatformID, botID string) *dalrecord.Key

NewBotKey creates the historical platform bot key.

func NewPlatformKey

func NewPlatformKey[PlatformID ~string](platformID PlatformID) *dalrecord.Key

NewPlatformKey creates the historical top-level platform key.

func NewPlatformUserKey

func NewPlatformUserKey[PlatformID ~string](platformID PlatformID, userID string) *dalrecord.Key

NewPlatformUserKey creates the historical platform-user key.

func NewWebhookUpdateKey

func NewWebhookUpdateKey(key botsfwstore.WebhookUpdateKey) *dalrecord.Key

NewWebhookUpdateKey stores the inbox under its bot to isolate equal provider update IDs from different Telegram bots.

Types

type AppUserStore

type AppUserStore interface {
	PrepareAppUser(ctx context.Context, identity botsfwstore.Identity) (botsfwstore.AppUser, error)
	EnsureAppUser(ctx context.Context, tx dal.ReadwriteTransaction, identity botsfwstore.Identity, prepared botsfwstore.AppUser) (botsfwstore.AppUser, error)
	AppUser(ctx context.Context, tx dal.ReadSession, botID, appUserID string) (botsfwstore.AppUser, error)
}

AppUserStore is the application-owned half of DALgo identity persistence. PrepareAppUser runs before the adapter transaction and may idempotently provision an external identity such as Firebase Auth. It must not persist the application user in DALgo. EnsureAppUser then persists that prepared user using only the supplied retryable transaction. This lets the adapter commit the application user, platform link, and chat atomically without repeating external side effects.

type BotUser

type BotUser = PlatformUserRecord

BotUser is a deprecated schema-level alias retained only to make application DALgo login tests readable during migration. New code should use PlatformUserRecord; public facades should return botsfwstore.PlatformUser.

type DBProvider

type DBProvider func(ctx context.Context) (dal.DB, error)

DBProvider returns the DALgo database for a request context. It supports hosts that select a database from tenant or request metadata.

type PlatformUserRecord

type PlatformUserRecord = dalrecord.DataWithID[string, botsfwmodels.PlatformUserData]

PlatformUserRecord is the DALgo representation of a platform user. It is exported for application-owned identity flows that intentionally operate on the historical schema without importing DALgo into bots-fw itself.

func GetPlatformUser

func GetPlatformUser(ctx context.Context, reader dal.ReadSession, platformID, userID string, data botsfwmodels.PlatformUserData) (PlatformUserRecord, error)

GetPlatformUser loads a platform user from the historical schema.

type StateStore

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

StateStore is the default DALgo-backed implementation of the framework store.

func NewStateStore

func NewStateStore(db dal.DB, appUsers AppUserStore, opts ...StateStoreOption) *StateStore

NewStateStore creates a DALgo state-store adapter.

func NewStateStoreWithProvider

func NewStateStoreWithProvider(getDB DBProvider, appUsers AppUserStore, opts ...StateStoreOption) *StateStore

NewStateStoreWithProvider creates a DALgo state-store adapter whose database is resolved for each operation.

func (*StateStore) AppUser

func (s *StateStore) AppUser(ctx context.Context, botID, appUserID string) (result botsfwstore.AppUser, err error)

func (*StateStore) ClaimWebhookUpdate

func (s *StateStore) ClaimWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseUntil time.Time) (claim botsfwstore.WebhookUpdateClaim, err error)

func (*StateStore) CompleteWebhookUpdate

func (s *StateStore) CompleteWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseID string) error

func (*StateStore) EnsureLinked

func (s *StateStore) EnsureLinked(ctx context.Context, request botsfwstore.LinkRequest) (linked botsfwstore.LinkedIdentity, err error)

func (*StateStore) FailWebhookUpdate

func (s *StateStore) FailWebhookUpdate(ctx context.Context, key botsfwstore.WebhookUpdateKey, leaseID string, failureCode botsfwstore.WebhookUpdateFailureCode) error

func (*StateStore) PlatformUser

func (s *StateStore) PlatformUser(ctx context.Context, identity botsfwstore.Identity, newData func() botsfwmodels.PlatformUserData) (result botsfwstore.PlatformUser, err error)

func (*StateStore) SaveChat

func (s *StateStore) SaveChat(ctx context.Context, identity botsfwstore.Identity, data botsfwmodels.BotChatData) error

func (*StateStore) SetPlatformUserAccessGranted

func (s *StateStore) SetPlatformUserAccessGranted(ctx context.Context, identity botsfwstore.Identity, newData func() botsfwmodels.PlatformUserData, value bool) (result botsfwstore.PlatformUser, err error)

type StateStoreOption

type StateStoreOption func(*StateStore)

StateStoreOption configures optional StateStore behaviour.

func WithClock

func WithClock(now func() time.Time) StateStoreOption

WithClock overrides the clock StateStore uses to stamp DtCreated/DtUpdated on platform-user and bot-chat records (via botsfwmodels.BotBaseData. EnsureTimestamps). It defaults to time.Now().UTC(). Tests should supply a fixed or stepped clock instead of relying on wall-clock time, so assertions about DtCreated/DtUpdated are deterministic.