server

type AuthHandler interface {
	// Authenticate validates the auth scheme, principal, and credentials.
	// On success it returns an Identity; on failure it returns a non-nil error.
	// Returning ErrAuthFailed causes the server to send a Failure with code
	// "Neo.ClientError.Security.Unauthorized". Returning ErrSchemeUnknown
	// causes a Failure with code "Neo.ClientError.Security.AuthProviderFailed".
	Authenticate(scheme, principal, credentials string) (Identity, error)
}

type BasicAuthHandler struct {
	// Validate is called with the principal and credentials from the client.
	// It must return nil on success and a non-nil error on failure.
	// See the type-level documentation for timing side-channel guidance.
	Validate func(principal, credentials string) error
}

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

type Identity struct {
	// Principal is the authenticated username or identifier.
	Principal string
}

type NoAuthHandler struct{}

type Options struct {
	// Auth is the authentication handler invoked during HELLO/LOGON. It is
	// the security boundary of the server: every client must satisfy it
	// before any Cypher statement executes.
	//
	// Auth must be set; leave it nil and [NewServer] returns
	// [ErrNoAuthHandler]. The server is secure-by-default: a nil Auth is NOT
	// silently replaced with an open, accept-everyone handler, so a careless
	// embedder writing Options{} cannot accidentally expose an
	// unauthenticated server. To enforce credentials, set Auth to a real
	// [AuthHandler] such as [BasicAuthHandler]. To run without authentication
	// (development or testing only) set Auth: [NoAuthHandler]{} explicitly:
	// the explicit NoAuthHandler value is itself the opt-in, it is
	// self-documenting at the call site, and it is impossible to set by
	// accident. In that case [NewServer] still emits a loud warning.
	Auth AuthHandler

	// Closer, when non-nil, is the store-level teardown owner for the
	// durability stack backing this server's engine — typically a
	// *[github.com/FlavioCFOliveira/GoGraph/store.DB] bundling the WAL writer
	// and the background checkpointer. The server closes it AFTER it has
	// drained every active connection, so it runs the one crash-safe teardown
	// order (stop the checkpoint goroutine, then close the WAL) only once no
	// in-flight transaction can still be writing. Both documented stop
	// mechanisms reach that teardown: [Server.Shutdown] closes it on its
	// drain-success branch, and [Server.Serve] closes it on its own exit path
	// once its connection drain completes (e.g. when the Serve context is
	// cancelled). The close is guarded by a [sync.Once] inside the server, so
	// the closer's Close runs exactly once regardless of which path wins or
	// whether both run; it need not be idempotent itself. Leave it nil for a
	// store-less engine or when the embedder tears the durability stack down
	// itself; the server then closes nothing beyond its connections.
	Closer io.Closer

	// TLSConfig, when non-nil, wraps accepted connections with TLS using
	// the given configuration verbatim. nil means plain TCP (no TLS).
	//
	// The server applies no MinVersion or cipher policy of its own: whatever
	// config is supplied here is used as-is. To start from a hardened baseline
	// (TLS 1.2 floor, modern AEAD/ECDHE cipher list), begin with
	// [DefaultTLSConfig] and add your own Certificates or GetCertificate before
	// assigning it here.
	TLSConfig *tls.Config

	// Logger is the structured logger for server events. When nil, the
	// default slog handler is used.
	Logger *slog.Logger

	// DatabaseName is the name this server reports as the database serving a
	// result, in the `db` field of the RUN and terminal PULL/DISCARD SUCCESS
	// metadata. Empty defaults to [DefaultDatabaseName].
	//
	// GoGraph serves exactly one graph per server, so this is a label rather
	// than a selector: a client that names a database in its session config has
	// that name echoed back (so its own bookkeeping stays consistent), and a
	// client that names none is told this value. The name is not validated and
	// an unknown name is not rejected — see [DefaultDatabaseName].
	//
	// Sending it at all matters because the field is not optional in practice:
	// the official neo4j-go-driver returns a nil DatabaseInfo from
	// ResultSummary.Database() when `db` is absent, so the idiomatic
	// summary.Database().Name() panics with a nil dereference inside the driver
	// (rmp #2172).
	DatabaseName string

	// MaxTxIdleTime bounds how long an OPEN explicit transaction may go without
	// the client sending a message, after which it is rolled back and the writer
	// serialisation and visibility barrier are released. Zero or negative defaults
	// to [DefaultMaxTxIdleTime]; there is no way to disable it, because an
	// unbounded idle transaction is the outage the round-3 audit demonstrated.
	//
	// This is NOT DefaultTxTimeout. That bounds a transaction's total life however
	// active it is; this reclaims one that has stopped talking. A busy transaction
	// resets it on every message and is limited only by the total bound.
	MaxTxIdleTime time.Duration

	// MaxOpenTxPerPrincipal caps how many explicit transactions one authenticated
	// principal may hold open at once across all of its connections. Exceeding it
	// fails the BEGIN with Neo.ClientError.General.LimitExceeded rather than
	// queueing. Zero defaults to [DefaultMaxOpenTxPerPrincipal]; a NEGATIVE value
	// disables enforcement, which is deliberate and visible at the call site.
	MaxOpenTxPerPrincipal int

	// MaxConnections is the upper bound on concurrent accepted connections.
	// Zero or negative values default to 1024.
	MaxConnections int

	// MaxMessageBytes caps the cumulative payload size of a single Bolt
	// message reassembled from per-chunk fragments. Zero or negative
	// values default to [proto.DefaultMaxMessageBytes] (16 MiB).
	// Bolt's wire format limits each chunk to 65535 bytes but the
	// chunk count is unbounded; this cap closes the Slowloris-style
	// DoS vector in which a malicious client streams non-zero chunks
	// indefinitely until the server OOMs.
	MaxMessageBytes int

	// MaxInboundDecodeBytes is the engine-wide ceiling, in bytes, on the total
	// decoded-collection memory in flight across ALL connections while messages
	// are being decoded. MaxMessageBytes bounds a single message and the decoder
	// bounds a single message's decoded collections, but without this aggregate
	// bound that per-message cap times MaxConnections is unbounded and reachable
	// before authentication — a memory-exhaustion DoS (CWE-770). When the pool is
	// drawn down, further inbound decodes fail fast with a retryable transient
	// error (backpressure) rather than allocating.
	//
	// Interpretation mirrors cypher.EngineOptions.GlobalMaxResultBytes:
	//   - 0 (the zero value) → derive from the Go soft memory limit: one eighth
	//     of GOMEMLIMIT when the operator has set one (results already claim half,
	//     and inbound decode is transient), else unlimited. This gives default-on
	//     protection precisely when a memory budget is declared, and never rejects
	//     a legitimate workload on a host whose memory the module cannot know.
	//   - [MaxInboundDecodeBytesUnlimited] (-1) → unlimited (explicit opt-out).
	//   - a positive value → used verbatim.
	//
	// GOMEMLIMIT alone cannot mitigate the DoS: in-flight decoded values are live,
	// non-collectable memory during decode, so the ceiling must gate before the
	// allocation.
	//
	// Scope: the ceiling bounds the concurrent DECODE-phase memory across
	// connections — the simultaneous-allocation vector that is the actual OOM
	// risk. A message's reserved bytes are returned as soon as it finishes
	// decoding, so this does not bound a message's lifetime while its handler
	// runs; a single connection may still transiently hold one decoded message
	// (bounded by MaxMessageBytes) during handling. This mirrors the result
	// ceiling's transient-vs-lifetime asymmetry.
	MaxInboundDecodeBytes int64

	// MaxInFlightPerConnection caps the total number of RUN statements
	// that may be issued within a single explicit transaction before
	// COMMIT or ROLLBACK. Zero or negative values default to
	// [DefaultMaxInFlightPerConnection] (1024). The count includes both
	// open (not yet fully PULL'd) and already-drained cursors
	// accumulated in tx.results since BEGIN; auto-commit cursors are
	// not counted (the Bolt v5 state machine already prevents two
	// concurrent auto-commit streams). The cap surfaces as a typed
	// Bolt FAILURE with code "Neo.ClientError.General.LimitExceeded".
	MaxInFlightPerConnection int

	// ConnTimeout is the per-connection idle read deadline applied throughout
	// the post-handshake message loop. Each time the server is about to read
	// the next message, the deadline is reset to now+ConnTimeout, so it bounds
	// the silent gap between messages rather than the total session duration.
	// Zero or negative values default to [DefaultConnTimeout] (30 s); a
	// non-zero deadline is always applied so an idle connection cannot hold its
	// slot and goroutine forever. Set a larger value for long-lived idle
	// sessions. The unauthenticated handshake phase is bounded separately and
	// is not configurable here; see [DefaultHandshakeTimeout].
	ConnTimeout time.Duration

	// MaxStatementTimeout is the server-side upper bound on per-statement
	// execution time. When a client supplies a timeout via the RUN or BEGIN
	// extra metadata, it is silently clamped to MaxStatementTimeout. When
	// a client supplies no timeout and MaxStatementTimeout is positive, the
	// server applies MaxStatementTimeout unconditionally. Zero means no
	// server-side cap (client controls its own timeout).
	MaxStatementTimeout time.Duration

	// DefaultTxTimeout is the bounded timeout applied to an explicit transaction
	// (opened by BEGIN) when the client supplies no tx_timeout. It guarantees the
	// engine's former single-writer serialisation, which an explicit transaction held
	// from BEGIN until COMMIT/ROLLBACK, can never be held indefinitely by an
	// abandoned transaction (#1302). Zero or negative values default to
	// [DefaultTxTimeout] (30 s). A client-supplied tx_timeout takes precedence;
	// MaxStatementTimeout, when set, additionally clamps the effective value. Set
	// a larger value for long-lived batch transactions.
	DefaultTxTimeout time.Duration

	// DefaultStatementTimeout is the bounded timeout applied to an AUTOCOMMIT
	// statement (a bare RUN outside an explicit transaction) when the client
	// supplies no per-statement `timeout` of its own. It is the autocommit
	// counterpart of DefaultTxTimeout: without it, a default-configured server
	// (MaxStatementTimeout left at zero) has no wall-clock bound on an
	// autocommit statement, so an authenticated client can pin a CPU core
	// indefinitely with a super-linear-runtime / single-row-result query whose
	// result-row and byte caps never fire (#1828). Zero or negative values
	// default to [DefaultStatementTimeout] (30 s). A client-supplied `timeout`
	// takes precedence; MaxStatementTimeout, when set, additionally clamps the
	// effective value. Set a larger value for long-running analytical statements.
	DefaultStatementTimeout time.Duration
}

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

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

type State uint8

type TransactionInfo struct {
	// StartedAt is when the BEGIN completed, from the server's clock.
	StartedAt time.Time

	// ID identifies the transaction for [Server.TerminateTransaction]. It is
	// unique for the lifetime of the server: a new transaction on the same
	// connection gets a new ID, so an ID captured from an earlier listing can
	// never terminate a later transaction that happens to reuse the connection.
	ID string

	// Principal is the authenticated identity that opened the transaction, empty
	// when the server runs without authentication and the client sent no
	// principal.
	Principal string

	// Remote is the client's network address, as the server sees it.
	Remote string

	// Mode is "w" for a writing transaction or "r" for a read-only one.
	//
	// NEITHER blocks anybody as of rmp #2305/#2306. A writing transaction used to
	// hold the engine's writer serialisation and the visibility barrier for its whole
	// lifetime, so an abandoned one was an outage and finding it was urgent; it now
	// holds only its own unpublished commit record and a reclamation-horizon slot.
	// What an abandoned writing transaction still costs is therefore version memory —
	// no version it can reach is reclaimable while it lives — not other clients'
	// progress.
	Mode string

	// State is the Bolt state machine state of the owning session, rendered for a
	// human — "TX_READY" between statements, "TX_STREAMING" while a result is
	// being drained.
	State string

	// Query is the text of the most recent statement RUN inside the transaction,
	// empty when BEGIN has not yet been followed by a RUN. It is the field that
	// answers "what is it doing?", which a counter and a log line cannot.
	Query string

	// Elapsed is how long the transaction has been open, measured at snapshot
	// time. It is provided rather than left to the caller because the server's
	// clock may be injected, and subtracting StartedAt from time.Now() would then
	// be wrong.
	Elapsed time.Duration
}

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