Documentation
¶
Overview ¶
Package mongodb implements a transparent MongoDB wire-protocol proxy for dbbat: it terminates client authentication (SASL PLAIN over TLS or a dbb_ API key), authenticates to the upstream MongoDB with stored credentials (SCRAM-SHA-256), and grant-checks, classifies, logs and quota-enforces every command — the same pipeline as the PostgreSQL/Oracle/MySQL proxies.
The wire framing is hand-rolled (no Go library offers a MongoDB *server* handshake) following the contract in specs/todos/2026-07-14-mongodb-support.md §1–§7. BSON document encode/decode uses go.mongodb.org/mongo-driver/v2/bson.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAuthenticationFailed — SASL PLAIN verification failed (bad password, // unknown user, or API-key mismatch). ErrAuthenticationFailed = errors.New("authentication failed") // ErrUpstreamRejected — the upstream MongoDB rejected our hello or SASL // exchange (ok != 1). ErrUpstreamRejected = errors.New("dbbat: upstream MongoDB rejected the exchange") // ErrDatabaseNotResolvable — the target dbbat database could not be // resolved from authSource / user#db / a single active grant. ErrDatabaseNotResolvable = errors.New("dbbat: could not resolve target database; " + "connect with authSource=<dbbat-database-name> (or username 'user#database')") // ErrNoActiveGrant — the user has no current grant on the resolved database. ErrNoActiveGrant = errors.New("dbbat: no active grant for this database") // ErrTLSRequired — a PLAIN auth attempt arrived on a non-TLS connection. ErrTLSRequired = errors.New("dbbat: PLAIN authentication requires TLS") // ErrUpstreamConnect — the outbound connection to the upstream MongoDB failed. ErrUpstreamConnect = errors.New("dbbat: upstream MongoDB connection failed") // ErrCommandBlocked — a command was refused by grant controls or the // always-blocked list. ErrCommandBlocked = errors.New("dbbat: command not permitted") // ErrPreAuthNotAllowed — a non-allowlisted command was issued before auth. ErrPreAuthNotAllowed = errors.New("dbbat: authentication required") // ErrQueryLimitExceeded — the grant's max_query_count quota has been reached. ErrQueryLimitExceeded = errors.New("dbbat: query count limit exceeded for this grant") // ErrDataLimitExceeded — the grant's max_bytes_transferred quota has been reached. ErrDataLimitExceeded = errors.New("dbbat: data transfer limit exceeded for this grant") )
Sentinel errors for the MongoDB proxy session lifecycle. The user-facing text is what a mongosh / driver surfaces in the errmsg field (contract §7).
var ( ErrShortMessage = errors.New("mongodb: message shorter than declared") ErrMessageTooLarge = errors.New("mongodb: message exceeds maximum size") ErrUnsupportedCompress = errors.New("mongodb: unsupported OP_COMPRESSED compressor") ErrCompressedSizeMismat = errors.New("mongodb: OP_COMPRESSED uncompressed size mismatch") ErrUnknownOpCode = errors.New("mongodb: unknown opcode") ErrBadSection = errors.New("mongodb: invalid OP_MSG section kind") ErrNoCommandBody = errors.New("mongodb: OP_MSG has no kind-0 command body") ErrEmptyCommandBody = errors.New("mongodb: empty command document") )
Wire-parsing errors.
var ErrTLSConfigInvalid = errors.New("mongodb tls: cert_file and key_file must both be set or both empty")
ErrTLSConfigInvalid is returned when only one of cert/key files is set.
Functions ¶
This section is empty.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the MongoDB proxy server. It accepts MongoDB client connections, authenticates them against the DBBat user store (SASL PLAIN / dbb_ API keys), and proxies commands to the upstream MongoDB configured for the requested database.
func NewServer ¶
func NewServer( dataStore *store.Store, encryptionKey []byte, queryStorage config.QueryStorageConfig, dumpConfig config.DumpConfig, authCache *cache.AuthCache, mongoConfig config.MongoConfig, logger *slog.Logger, ) (*Server, error)
NewServer creates a new MongoDB proxy server.
func (*Server) Addr ¶
Addr returns the listener's bound address, or nil if the server has not started accepting connections yet.
func (*Server) SetApprovalDeps ¶ added in v0.20.0
func (s *Server) SetApprovalDeps(deps shared.ApprovalDeps)
SetApprovalDeps installs the approval-hold collaborators. A server without them never holds anything.
func (*Server) SetRowWriter ¶ added in v0.20.0
SetRowWriter installs the process-wide result-row writer, replacing (and shutting down) the private one NewServer created. Batching across every protocol is where the design pays off most: a busy proxy with many small result sets then issues one INSERT per ~1000 rows overall rather than one per query.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a single client connection through the MongoDB proxy.
func (*Session) KillHeldQuery ¶ added in v0.20.0
KillHeldQuery ends a command parked on a human, in response to a MongoDB killOperations. Reports whether anything was parked.
func (*Session) Run ¶
Run drives the session lifecycle (contract §2):
- optional TLS termination (peek first byte)
- PRE-AUTH: answer hello/ping/etc — monitoring connections stay here forever, never dialing upstream or recording a connection
- on saslStart: authenticate, resolve grant, dial upstream, record
- relay commands until either side closes