refactor: whitelist public API exports and privatize internals

.gitignore

@@ -32,3 +32,5 @@ htmldocs/
 htmdocs/
 
 *.out
+audit/
+.audit/

async_postgres.nim

@@ -134,6 +134,134 @@ import
     pg_pool_cluster, pg_largeobject, pg_advisory_lock, pg_sql, pg_replication,
   ]
 
-export
-  async_backend, pg_protocol, pg_auth, pg_types, pg_connection, pg_client, pg_pool,
-  pg_pool_cluster, pg_largeobject, pg_advisory_lock, pg_sql, pg_replication
+# `pg_types`/`pg_connection`/`pg_client` whitelist themselves; the other
+# modules expose only their public API surface.
+export pg_types, pg_connection, pg_client
+export pg_pool_cluster, pg_largeobject, pg_advisory_lock, pg_sql, pg_replication
+export pg_auth
+
+# `pg_pool` — public pool API (internal gauges/helpers stay in the module).
+export pg_pool.PoolConfig
+export pg_pool.PoolMetrics
+export pg_pool.PooledConnHandle
+export pg_pool.PgPool
+export pg_pool.initPoolConfig
+export pg_pool.idleCount
+export pg_pool.activeCount
+export pg_pool.size
+export pg_pool.isClosed
+export pg_pool.metrics
+export pg_pool.resetSession
+export pg_pool.newPool
+export pg_pool.release
+export pg_pool.resetSessionAndRelease
+export pg_pool.acquire
+export pg_pool.runAndRelease
+export pg_pool.withConnection
+export pg_pool.exec
+export pg_pool.query
+export pg_pool.queryEach
+export pg_pool.queryRow
+export pg_pool.queryRowOpt
+export pg_pool.queryValue
+export pg_pool.queryValueOpt
+export pg_pool.queryValueOrDefault
+export pg_pool.queryExists
+export pg_pool.queryColumn
+export pg_pool.simpleQuery
+export pg_pool.simpleExec
+export pg_pool.execInTransaction
+export pg_pool.queryInTransaction
+export pg_pool.notify
+export pg_pool.withTransaction
+export pg_pool.withTransactionRetry
+export pg_pool.withTransactionDeadline
+export pg_pool.withTransactionRetryDeadline
+export pg_pool.withPipeline
+export pg_pool.close
+
+# `async_backend` is exported wholesale; it also re-exports the selected
+# backend (asyncdispatch / chronos), supplying `async`, `waitFor`, etc.
+export async_backend
+
+# `pg_protocol` — the wire protocol codec and entry points. The inbound
+# decoders and leaf encoders stay internal; the send-buffer helpers are
+# re-exported because the `addParseDirect`/`addBindDirect` macros and advanced
+# call sites resolve them in the caller's scope.
+export pg_protocol.FrontendMessageKind
+export pg_protocol.BackendMessageKind
+export pg_protocol.DescribeKind
+export pg_protocol.TransactionStatus
+export pg_protocol.FieldDescription
+export pg_protocol.CopyFormat
+export pg_protocol.BackendMessage
+export pg_protocol.ParseState
+export pg_protocol.ParseResult
+export pg_protocol.RowData
+export pg_protocol.Row
+export pg_protocol.syncMsg
+export pg_protocol.flushMsg
+export pg_protocol.copyDoneMsg
+export pg_protocol.BinarySafeOids
+export pg_protocol.maxInt32Len
+export pg_protocol.DefaultMaxBackendMessageLen
+export pg_protocol.MaxNegotiateProtocolOptions
+export pg_protocol.MaxErrorOrNoticeFields
+export pg_protocol.MaxSaslMechanisms
+export pg_protocol.initRow
+export pg_protocol.data
+export pg_protocol.rowIdx
+export pg_protocol.isBinarySafeOid
+export pg_protocol.addInt16
+export pg_protocol.addInt32
+export pg_protocol.addCount16
+export pg_protocol.addLen32
+export pg_protocol.addCString
+export pg_protocol.patchMsgLen
+export pg_protocol.encodeStartup
+export pg_protocol.encodeSSLRequest
+export pg_protocol.encodePassword
+export pg_protocol.encodeSASLInitialResponse
+export pg_protocol.encodeSASLResponse
+export pg_protocol.encodeQuery
+export pg_protocol.addParse
+export pg_protocol.addBind
+export pg_protocol.addBindRaw
+export pg_protocol.addDescribe
+export pg_protocol.addExecute
+export pg_protocol.addClose
+export pg_protocol.addSync
+export pg_protocol.addFlush
+export pg_protocol.addCopyDone
+export pg_protocol.encodeParse
+export pg_protocol.encodeBind
+export pg_protocol.encodeDescribe
+export pg_protocol.encodeExecute
+export pg_protocol.encodeClose
+export pg_protocol.encodeSync
+export pg_protocol.encodeFlush
+export pg_protocol.encodeTerminate
+export pg_protocol.encodeCancelRequest
+export pg_protocol.encodeCopyData
+export pg_protocol.encodeCopyDone
+export pg_protocol.encodeCopyFail
+export pg_protocol.newRowData
+export pg_protocol.reuseRowData
+export pg_protocol.clone
+export pg_protocol.buildResultFormats
+export pg_protocol.parseDataRowInto
+export pg_protocol.parseBackendMessage
+export pg_protocol.formatError
+export pg_protocol.addCopyBinaryHeader
+export pg_protocol.addCopyBinaryTrailer
+export pg_protocol.addCopyTupleStart
+export pg_protocol.addCopyFieldNull
+export pg_protocol.addCopyFieldInt16
+export pg_protocol.addCopyFieldInt32
+export pg_protocol.addCopyFieldInt64
+export pg_protocol.addCopyFieldFloat64
+export pg_protocol.addCopyFieldFloat32
+export pg_protocol.addCopyFieldBool
+export pg_protocol.addCopyFieldText
+export pg_protocol.addCopyFieldString
+export pg_protocol.encodeStandbyStatusUpdate

async_postgres/pg_advisory_lock.nim

@@ -79,6 +79,7 @@
 import std/[macros, importutils]
 
 import async_backend, pg_protocol, pg_types, pg_connection, pg_client
+import pg_connection/types
 
 privateAccess(PgConnection)
 

async_postgres/pg_client.nim

@@ -77,6 +77,68 @@ export core.RetryOptions
 export core.isRetryableTxError
 export core.backoffDelayMs
 
-export
-  exec, query, prepared, copy, transaction, transaction_helpers, pipeline, cursor,
-  direct
+# `exec` — exec / notify entry points (the `*Impl` helpers stay internal).
+export exec.exec
+export exec.notify
+
+# `query` — query entry points and result accessors (`*Impl` stay internal).
+export query.query
+export query.queryEach
+export query.queryRow
+export query.queryRowOpt
+export query.queryValue
+export query.queryValueOpt
+export query.queryValueOrDefault
+export query.queryExists
+export query.queryColumn
+
+# `prepared` — prepared statements.
+export prepared.PreparedStatement
+export prepared.columnIndex
+export prepared.prepare
+export prepared.execute
+export prepared.close
+
+# `copy` — COPY IN / COPY OUT entry points (`*Impl` stay internal).
+export copy.copyIn
+export copy.copyInStream
+export copy.copyOut
+export copy.copyOutStream
+
+# `transaction` — transaction/savepoint scoping macros. `rollbackGrace` is
+# re-exported because pg_pool's deadline macros resolve it via `bindSym`.
+export transaction.withTransaction
+export transaction.withTransactionRetry
+export transaction.withSavepoint
+export transaction.withTransactionDeadline
+export transaction.withTransactionRetryDeadline
+export transaction.withSavepointDeadline
+export transaction.rollbackGrace
+
+# `transaction_helpers` — the two in-transaction convenience helpers.
+export transaction_helpers.execInTransaction
+export transaction_helpers.queryInTransaction
+
+# `pipeline` — batching.
+export pipeline.Pipeline
+export pipeline.PipelineResult
+export pipeline.PipelineResultKind
+export pipeline.IsolatedPipelineResults
+export pipeline.newPipeline
+export pipeline.reset
+export pipeline.addExec
+export pipeline.addQuery
+export pipeline.execute
+export pipeline.executeIsolated
+
+# `cursor` — result cursors.
+export cursor.Cursor
+export cursor.columnIndex
+export cursor.fetchNext
+export cursor.close
+export cursor.withCursor
+export cursor.openCursor
+
+# `direct` — zero-allocation macros.
+export direct.queryDirect
+export direct.execDirect

async_postgres/pg_client/copy.nim

@@ -4,6 +4,7 @@
 import std/[options]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, simple_query]
 import ./core
 
 proc pollCopyInError(
@@ -88,7 +89,7 @@ proc abortCopyWatch(conn: PgConnection, watch: RecvWatch) =
   watch.cancel()
   conn.state = csClosed
 
-proc copyInRawImpl*(
+proc copyInRawImpl(
     conn: PgConnection, sql: string, data: seq[byte]
 ): Future[string] {.async.} =
   conn.checkReady()
@@ -263,7 +264,7 @@ proc copyIn*(
     offset += chunk.len
   copyIn(conn, sql, combined, timeout)
 
-proc copyInStreamImpl*(
+proc copyInStreamImpl(
     conn: PgConnection, sql: string, callback: CopyInCallback
 ): Future[CopyInInfo] {.async.} =
   conn.checkReady()
@@ -496,7 +497,7 @@ proc copyInStream*(
     )
   return info
 
-proc copyOutImpl*(conn: PgConnection, sql: string): Future[CopyResult] {.async.} =
+proc copyOutImpl(conn: PgConnection, sql: string): Future[CopyResult] {.async.} =
   conn.checkReady()
   let msg = encodeQuery(sql)
   conn.state = csBusy
@@ -569,7 +570,7 @@ proc copyOut*(
     awaitOrInvalidate(conn, cr, copyOutImpl(conn, sql), timeout, "COPY OUT timed out")
   return cr
 
-proc copyOutStreamImpl*(
+proc copyOutStreamImpl(
     conn: PgConnection, sql: string, callback: CopyOutCallback
 ): Future[CopyOutInfo] {.async.} =
   conn.checkReady()

async_postgres/pg_client/core.nim

@@ -8,6 +8,8 @@
 import std/[options, tables, math, random]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 
 type
   IsolationLevel* = enum

async_postgres/pg_client/cursor.nim

@@ -4,6 +4,7 @@
 import std/[options]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query, lifecycle]
 import ./core
 
 type Cursor* = ref object

async_postgres/pg_client/direct.nim

@@ -4,6 +4,8 @@
 import std/[algorithm, macros, options, sets, tables]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 import ./core
 
 proc queryDirectRunImpl*(

async_postgres/pg_client/exec.nim

@@ -4,6 +4,8 @@
 import std/[options, tables]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 import ./core
 
 proc execImpl*(

async_postgres/pg_client/pipeline.nim

@@ -5,6 +5,8 @@
 import std/[options, tables]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 import core
 
 type

async_postgres/pg_client/prepared.nim

@@ -3,6 +3,8 @@
 import std/[options]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 import ./core
 
 type PreparedStatement* = object

async_postgres/pg_client/query.nim

@@ -5,6 +5,8 @@
 import std/[options, tables]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, cache, simple_query]
+import ../pg_types/encoding
 import ./core
 
 proc queryImpl*(

async_postgres/pg_client/transaction.nim

@@ -4,9 +4,10 @@
 import std/[macros, options]
 
 import ../[async_backend, pg_protocol, pg_connection]
+import ../pg_connection/[types, simple_query]
 import ./core
 
-proc hasReturnStmt*(n: NimNode): bool =
+proc hasReturnStmt(n: NimNode): bool =
   ## Check whether an AST contains a `return` statement (excluding nested
   ## proc/func/method/iterator definitions where `return` is valid).
   if n.kind == nnkReturnStmt:
@@ -25,7 +26,7 @@ proc escapeLabelName(n: NimNode): string =
   ## Plain name of a `break`/`continue`/`block` label (`nnkIdent` or `nnkSym`).
   n.strVal
 
-proc hasLoopEscapeStmt*(n: NimNode): bool =
+proc hasLoopEscapeStmt(n: NimNode): bool =
   ## True if a `break`/`continue` in `n` would escape to a loop or `block:`
   ## outside the body, skipping the trailing COMMIT / RELEASE. Statements
   ## captured by a body-local loop/`block` are accepted.
@@ -189,7 +190,7 @@ proc buildRollbackCleanup*(connSym, rollbackTimeout: NimNode): NimNode =
           newException(PgError, `cleanupDefectSym`.msg, `cleanupDefectSym`),
         )
 
-proc buildSavepointRollbackCleanup*(
+proc buildSavepointRollbackCleanup(
     connSym, spNameSym, rollbackTimeout: NimNode
 ): NimNode =
   ## Build the shared `onCleanupSkipped`-wired ROLLBACK TO SAVEPOINT cleanup used
@@ -237,7 +238,7 @@ proc buildSavepointRollbackCleanup*(
           newException(PgError, `cleanupDefectSym`.msg, `cleanupDefectSym`),
         )
 
-proc buildDeadlineAwaitAndTimeout*(
+proc buildDeadlineAwaitAndTimeout(
     connSym, bodyFnSym, totalDurSym: NimNode, reason: string, catchableCleanup: NimNode
 ): NimNode =
   ## Build the single-attempt deadline-bounded await + timeout handler shared

async_postgres/pg_client/transaction_helpers.nim

@@ -5,6 +5,7 @@
 import std/[options]
 
 import ../[async_backend, pg_protocol, pg_connection, pg_types]
+import ../pg_connection/[types, buffer_io, simple_query]
 import ./core
 
 proc queryInTransactionImpl(