Struct Conn 

pub struct Conn<Transport, Phase, Cleanliness = Pristine> { /* private fields */ }

A connection whose legal operations are selected by Phase and Cleanliness.

Implementations

impl<S: TlsServerEndPoint, Phase, Cleanliness> Conn<S, Phase, Cleanliness>

pub fn tls_server_end_point(&self) -> &[u8]

Returns the peer-certificate binding for custom authentication policy.

impl<S> Conn<S, Startup, Pristine>

pub fn authentication(self) -> Conn<S, Auth>

Enters backend-driven authentication after sending the startup message.

impl<S> Conn<S, Auth, Pristine>

pub fn offer_backend( self, message: BackendMessage, ) -> Result<AuthEvent<S>, (Self, BackendMessage, Option<Error>)>

Projects either protocol negotiation or an authentication request.

Errors

Returns an authentication parsing error, or the unchanged connection and message when the backend message is unrelated to startup authentication.

Panics

Panics only if the exhaustive continuation guard above the internal projection becomes inconsistent with Self::offer.

pub fn offer(self, authentication: Authentication) -> Result<AuthOffer<S>>

Applies one backend authentication request to the session state.

Errors

SASL continuation/final messages are rejected before SASL is selected.

impl<S> Conn<S, TokenResponse, Pristine>

pub fn respond(self, token: Bytes) -> (Conn<S, TokenChallenge>, Frame)

Sends a GSS, SSPI, or Kerberos token and waits for continuation or success.

impl<S> Conn<S, TokenChallenge, Pristine>

pub fn offer( self, message: BackendMessage, ) -> Result<TokenAuthEvent<S>, (Self, BackendMessage)>

Projects recursive GSS continuation, successful authentication, or failure.

Errors

Returns the live connection and message for an illegal response.

impl<S> Conn<S, PasswordResponse, Pristine>

pub fn password( self, password: &[u8], ) -> Result<(Conn<S, AwaitingAuthOk>, Frame)>

Sends a cleartext or precomputed MD5 password response.

Errors

Returns an error if the response contains a NUL byte or is too large.

impl<S> Conn<S, SaslInitial, Pristine>

pub fn scram_sha_256(self, initial: &[u8]) -> Result<(Conn<S, Sasl>, Frame)>

Selects SCRAM without channel binding.

Errors

Returns an error if the initial response is too large.

impl<S: TlsServerEndPoint> Conn<S, SaslInitial, Pristine>

pub fn scram_sha_256_plus( self, initial: &[u8], ) -> Result<(Conn<S, Sasl>, Frame)>

Selects SCRAM-PLUS. This method is unavailable on transports which cannot provide the peer-certificate channel binding.

Errors

Returns an error if the initial response is too large.

impl<S> Conn<S, Sasl, Pristine>

pub fn offer( self, authentication: Authentication, ) -> Result<SaslEvent<S>, (Self, Authentication)>

Projects the next server challenge or final verifier.

Errors

Returns the live connection and authentication message for an illegal branch.

pub fn offer_backend( self, message: BackendMessage, ) -> Result<SaslEvent<S>, (Self, BackendMessage)>

Projects an authentication error which terminates an active SASL exchange.

Errors

Returns the live connection and message for an illegal response.

impl<S> Conn<S, SaslChallenge, Pristine>

pub fn respond(self, response: Bytes) -> (Conn<S, Sasl>, Frame)

Sends the response to one received challenge and re-enters the SASL loop.

impl<S> Conn<S, SaslFinal, Pristine>

pub fn verified(self) -> Conn<S, AwaitingAuthOk>

Records that custom SCRAM logic verified the received server-final value.

impl<S> Conn<S, AwaitingAuthOk, Pristine>

pub fn offer( self, message: BackendMessage, ) -> Result<AuthCompletion<S>, (Self, BackendMessage)>

Requires backend evidence that authentication succeeded or failed.

Errors

Returns the live connection and message for an illegal response.

impl<S> Conn<S, AwaitingStartupReady, Pristine>

pub fn offer_ready( self, item: SessionItem, ) -> Result<Conn<S, Ready>, (Self, SessionItem)>

Completes startup only when presented with a projected ReadyForQuery.

Errors

Returns the unchanged connection and item when it is not ReadyForQuery.

impl<S, P: 'static, C: 'static> Conn<S, P, C>

pub fn erase(self) -> ErasedConn<S>

Erases monomorphised state markers while retaining their exact runtime identities for checked re-entry.

impl<S> Conn<S, PreStartup, Pristine>

pub fn ssl_request(self) -> (Conn<S, AwaitingSslReply>, [u8; 8])

Encodes SSLRequest and enters the raw-reply phase.

pub fn gssenc_request(self) -> (Conn<S, AwaitingGssReply>, [u8; 8])

Encodes GSSENCRequest and enters the raw-reply phase.

pub fn startup( self, message: &StartupMessage, ) -> Result<(Conn<S, Startup>, Bytes)>

Encodes and enters the startup phase.

Errors

Returns an error when the startup parameters cannot be encoded.

pub fn cancel_request( self, process_id: u32, secret_key: &[u8], ) -> Result<(Conn<S, Terminated>, Bytes)>

Encodes a version 3.0 or 3.2 out-of-band cancellation request.

Errors

Returns an error unless the cancellation key is between 4 and 256 bytes.

impl<S, C> Conn<S, PreStartup, C>

pub fn offer_pre_startup( self, message: PreStartupMessage, ) -> PreStartupOffer<S, C>

Projects an inspected client pre-startup packet into the server role.

impl<S, C> Conn<S, ServerSslDecision, C>

pub fn reject_ssl(self) -> (Conn<S, PreStartup, C>, u8)

Rejects SSL and returns to the pre-startup choice on the same transport.

pub fn accept_ssl(self) -> (Conn<S, TlsHandshake, C>, u8)

Accepts SSL and requires the transport handshake before startup is legal.

pub fn legacy_ssl_error(self) -> (Conn<S, Terminated, C>, u8)

Emits the historical raw E response and terminates negotiation.

impl<S, C> Conn<S, ServerGssDecision, C>

pub fn reject_gss(self) -> (Conn<S, PreStartup, C>, u8)

Sends N and returns to plaintext pre-startup choice.

pub fn accept_gss(self) -> (Conn<S, GssHandshake, C>, u8)

Sends S and requires a server-side GSS transport handshake.

pub fn legacy_gss_error(self) -> (Conn<S, Terminated, C>, u8)

Emits the historical raw E response and terminates negotiation.

impl<S, C> Conn<S, AwaitingSslReply, C>

pub fn receive_reply( self, reply: EncryptionReply, ) -> Negotiation<S, TlsHandshake, C>

Resolves the raw SSL response byte.

A pending negotiation cannot send a startup message:

use pg_proto::Conn;
let (pending, _) = Conn::new(()).ssl_request();
let _ = pending.startup();

pub fn apply_ssl_reply( self, reply: EncryptionReply, mode: SslMode, ) -> SslModeNegotiation<S, C>

Resolves the SSL response while enforcing an SslMode’s fallback rule.

impl<S, C> Conn<S, AwaitingGssReply, C>

pub fn receive_reply( self, reply: EncryptionReply, ) -> Negotiation<S, GssHandshake, C>

Applies the server’s GSS encryption decision byte.

impl<S, C> Conn<S, TlsHandshake, C>

pub fn finish_tls<Tls>( self, upgrade: impl FnOnce(S) -> Tls, ) -> Conn<Tls, PreStartup, C>

Records a completed in-place TLS upgrade, changing the transport type.

impl<S, C> Conn<S, TlsHandshake, C>

pub fn finish_server_tls<Tls>( self, upgrade: impl FnOnce(S) -> Tls, ) -> Conn<Tls, PreStartup, C>

Records a server-side TLS upgrade while preserving cleanliness.

impl<S> Conn<S, GssHandshake, Pristine>

pub fn finish_gss<Gss>( self, upgrade: impl FnOnce(S) -> Gss, ) -> Conn<Gss, PreStartup>

Records a completed in-place GSS encryption upgrade.

impl<S, C> Conn<S, GssHandshake, C>

pub fn finish_server_gss<Gss>( self, upgrade: impl FnOnce(S) -> Gss, ) -> Conn<Gss, PreStartup, C>

Completes a server-side GSS upgrade and returns to encrypted pre-startup.

impl<S, C> Conn<S, Startup, C>

pub fn validate_protocol( self, message: StartupMessage, newest: ProtocolVersion, ) -> ServerProtocolOffer<S, C>

Validates the startup protocol before authentication can begin.

impl<S, C> Conn<S, ServerStartupValidated, C>

pub fn begin_server_auth(self) -> Conn<S, ServerAuth, C>

Begins proxy-side authentication of a protocol-compatible client.

impl<S, C> Conn<S, ServerStartupRejected, C>

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, Terminated, C>, Frame)>

Rejects an unsupported major protocol version and terminates the session.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerAuth, C>

pub fn request_cleartext(self) -> Result<(Conn<S, ServerPassword, C>, Frame)>

Requests a cleartext password from the client.

Errors

Returns an error only if the fixed authentication message cannot be encoded.

pub fn request_md5( self, salt: [u8; 4], ) -> Result<(Conn<S, ServerPassword, C>, Frame)>

Requests a PostgreSQL MD5 password response from the client.

Errors

Returns an error only if the authentication message cannot be encoded.

pub fn request_sasl( self, mechanisms: Vec<Bytes>, ) -> Result<(Conn<S, ServerSaslInitial, C>, Frame)>

Offers one or more SASL mechanisms to the client.

Errors

Returns an error if a mechanism contains a NUL byte.

pub fn request_kerberos_v5( self, ) -> Result<(Conn<S, ServerAuthResponse, C>, Frame)>

Requests Kerberos V5 authentication.

Errors

Returns an error only if the fixed authentication message cannot be encoded.

pub fn request_gss(self) -> Result<(Conn<S, ServerAuthResponse, C>, Frame)>

Requests GSSAPI authentication.

Errors

Returns an error only if the fixed authentication message cannot be encoded.

pub fn request_sspi(self) -> Result<(Conn<S, ServerAuthResponse, C>, Frame)>

Requests SSPI authentication.

Errors

Returns an error only if the fixed authentication message cannot be encoded.

pub fn authentication_ok( self, ) -> Result<(Conn<S, ServerStartupReady, C>, Frame)>

Confirms authentication and enters the startup-completion phase.

Errors

Returns an error only if the fixed authentication message cannot be encoded.

impl<S, C> Conn<S, ServerPassword, C>

pub fn receive_password( self, message: FrontendMessage, ) -> PasswordProjection<S, C>

Projects the inspected password response and returns to policy evaluation.

Errors

Returns the unchanged state and message if it is not a valid password response.

impl<S, C> Conn<S, ServerSaslInitial, C>

pub fn receive_initial( self, message: FrontendMessage, ) -> SaslInitialProjection<S, C>

Projects the client’s selected SASL mechanism and initial response.

Errors

Returns the unchanged state and message if the SASL initial response is malformed.

impl<S, C> Conn<S, ServerSasl, C>

pub fn receive_response( self, message: FrontendMessage, ) -> ServerProjection<(Self, Bytes), S, ServerSasl, C>

Projects one client SASL response and remains in the recursive exchange.

Errors

Returns the unchanged state and message if it is not a SASL response.

pub fn continue_with(self, challenge: Bytes) -> Result<(Self, Frame)>

Sends a SASL challenge and remains in the recursive exchange.

Errors

Returns an error only if the authentication message cannot be encoded.

pub fn finish( self, server_final: Bytes, ) -> Result<(Conn<S, ServerAuth, C>, Frame)>

Sends verified server-final data and returns to authentication completion.

Errors

Returns an error only if the authentication message cannot be encoded.

impl<S, C> Conn<S, ServerAuthResponse, C>

pub fn receive_response( self, message: FrontendMessage, ) -> ServerProjection<(Self, Bytes), S, ServerAuthResponse, C>

Projects one GSS, SSPI, or Kerberos response token.

Errors

Returns the unchanged state and message if it is not an authentication token.

pub fn continue_gss(self, token: Bytes) -> Result<(Self, Frame)>

Sends a GSS continuation token and remains in the authentication exchange.

Errors

Returns an error only if the authentication message cannot be encoded.

pub fn verified(self) -> Conn<S, ServerAuth, C>

Returns to policy evaluation after the mechanism verifies its response.

impl<S, C> Conn<S, ServerStartupReady, C>

pub fn parameter_status( self, name: Bytes, value: Bytes, ) -> Result<(Self, Frame)>

Emits a startup parameter while remaining before ReadyForQuery.

Errors

Returns an error if either value contains a NUL byte.

pub fn backend_key_data( self, process_id: u32, secret_key: Bytes, ) -> Result<(Self, Frame)>

Emits the proxy-minted cancellation key exposed to this client.

Errors

Returns an error if the key is outside the protocol’s 4–256 byte range.

pub fn negotiate_protocol( self, newest: ProtocolVersion, unsupported_options: Vec<Bytes>, ) -> Result<(Self, Frame)>

Responds to unsupported protocol 3.1/3.2 startup options.

Errors

Returns an error if an option name contains a NUL byte or counts overflow.

pub fn ready(self) -> Result<(Conn<S, Ready, C>, Frame)>

Completes startup with an idle ReadyForQuery.

Errors

Returns an error only if the fixed message cannot be encoded.

impl<S, C> Conn<S, Ready, C>

pub fn offer_frontend(self, message: FrontendMessage) -> ReadyProjection<S, C>

Projects an inspected client message into the server-role ready state.

Errors

Returns the unchanged connection and message for choices not yet legal in this simple-query projection.

pub fn accept_stateless_query( self, query: Bytes, ) -> (Conn<S, ServerSimpleQuery, C>, Bytes)

Accepts inspected query text which cannot retain client session state.

pub fn accept_stateless_function_call( self, message: FunctionCall, ) -> (Conn<S, ServerFunctionCall, C>, FunctionCall)

Accepts an allow-listed function call known not to retain session state.

impl<S, C> Conn<S, ServerFunctionCall, C>

pub fn respond( self, value: Bytes, ) -> Result<(Conn<S, ServerFunctionCallDone, C>, Frame)>

Sends the typed function result before the mandatory ready message.

Errors

Returns an error if the result is too large for a wire frame.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerFunctionCallError, C>, Frame)>

Rejects the call before the mandatory ready message.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerFunctionCallDone, C>

pub fn ready( self, status: TransactionStatus, ) -> Result<(ServerReadyState<S, C>, Frame)>

Sends readiness after a successful function call.

Errors

Returns an error only if the fixed ready message cannot be encoded.

impl<S, C> Conn<S, ServerFunctionCallError, C>

pub fn ready( self, status: TransactionStatus, ) -> Result<(ServerReadyState<S, C>, Frame)>

Sends readiness after a failed function call.

Errors

Returns an error only if the fixed ready message cannot be encoded.

impl<S, C> Conn<S, ServerBuilding, C>

pub fn offer_frontend( self, message: FrontendMessage, ) -> ExtendedProjection<S, ServerBuilding, C>

Projects the next inspected message in an extended-query pipeline.

Errors

Returns the unchanged state and message if it is not legal before Sync.

impl<S, C> Conn<S, ServerSimpleQuery, C>

pub fn send(self, message: &BackendMessage) -> Result<(Self, Frame)>

Sends a non-terminal typed result message after proxy inspection or rewriting.

Errors

Returns an error if the message cannot be reconstructed, or if it would prematurely change the simple-query state.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerSimpleError, C>, Frame)>

Sends an error response before the mandatory ReadyForQuery.

Errors

Returns an error if a diagnostic field is invalid.

pub fn copy_in(self, response: CopyResponse) -> CopyInStart<S, C, CopySimple>

Starts a simple-query COPY IN sub-session.

Errors

Returns an error if the format count overflows the protocol field.

pub fn copy_out(self, response: CopyResponse) -> CopyOutStart<S, C, CopySimple>

Starts a simple-query COPY OUT sub-session.

Errors

Returns an error if the format count overflows the protocol field.

pub fn copy_both( self, response: CopyResponse, ) -> CopyBothStart<S, C, CopySimple>

Starts a simple-query COPY BOTH sub-session.

Errors

Returns an error if the format count overflows the protocol field.

pub fn ready( self, status: TransactionStatus, ) -> Result<(ServerReadyState<S, C>, Frame)>

Ends a successful simple-query exchange and surfaces transaction status.

Errors

Returns an error only if the fixed ready message cannot be encoded.

impl<S, C> Conn<S, ServerSimpleError, C>

pub fn ready( self, status: TransactionStatus, ) -> Result<(ServerReadyState<S, C>, Frame)>

Ends an errored simple-query exchange and surfaces transaction status.

Errors

Returns an error only if the fixed ready message cannot be encoded.

impl<S, C> Conn<S, ServerParse, C>

pub fn complete(self) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Confirms a successful Parse and returns to the building loop.

Errors

Returns an error only if the fixed response cannot be encoded.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Rejects Parse and begins discarding the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerBind, C>

pub fn complete(self) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Confirms a successful Bind and returns to the building loop.

Errors

Returns an error only if the fixed response cannot be encoded.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Rejects Bind and begins discarding the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerClose, C>

pub fn complete(self) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Confirms Close and returns to the building loop.

Errors

Returns an error only if the fixed response cannot be encoded.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Rejects Close and begins discarding the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerDescribe, C>

pub fn parameter_description(self, oids: Vec<u32>) -> Result<(Self, Frame)>

Sends statement parameter OIDs before its row metadata.

Errors

Returns an error if the OID count overflows the protocol field.

pub fn row_description( self, description: RowDescription, ) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Sends reconstructable row metadata and returns to the building loop.

Errors

Returns an error if field metadata is invalid.

pub fn no_data(self) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Sends NoData and returns to the building loop.

Errors

Returns an error only if the fixed response cannot be encoded.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Rejects Describe and begins discarding the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerExecute, C>

pub fn send(self, message: &BackendMessage) -> Result<(Self, Frame)>

Sends a non-terminal result message for Execute.

Errors

Returns an error if the message cannot be reconstructed or requires a dedicated state transition.

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Completes execution and returns to the building loop.

Errors

Returns an error if the command tag contains a NUL byte.

pub fn portal_suspended(self) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Suspends a portal and returns to the building loop.

Errors

Returns an error only if the fixed response cannot be encoded.

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Rejects Execute and begins discarding the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

pub fn copy_in(self, response: CopyResponse) -> CopyInStart<S, C, CopyExtended>

Starts an extended-query COPY IN sub-session.

Errors

Returns an error if the format count overflows the protocol field.

pub fn copy_out( self, response: CopyResponse, ) -> CopyOutStart<S, C, CopyExtended>

Starts an extended-query COPY OUT sub-session.

Errors

Returns an error if the format count overflows the protocol field.

pub fn copy_both( self, response: CopyResponse, ) -> CopyBothStart<S, C, CopyExtended>

Starts an extended-query COPY BOTH sub-session.

Errors

Returns an error if the format count overflows the protocol field.

impl<S, C> Conn<S, ServerCopyIn<CopySimple>, C>

pub fn offer_frontend( self, message: FrontendMessage, ) -> CopyInProjection<S, C, CopySimple>

Projects one inspected frontend message inside COPY IN.

Errors

Returns the unchanged state and message for anything other than COPY data, completion, or failure.

impl<S, C> Conn<S, ServerCopyIn<CopyExtended>, C>

pub fn offer_frontend( self, message: FrontendMessage, ) -> CopyInProjection<S, C, CopyExtended>

Projects one inspected frontend message inside extended-query COPY IN.

Errors

Returns the unchanged state and message for anything other than COPY data, completion, or failure.

impl<S, C> Conn<S, ServerCopyInDone<CopySimple>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerSimpleQuery, C>, Frame)>

Completes simple-query COPY IN before ReadyForQuery.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C> Conn<S, ServerCopyInDone<CopyExtended>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Completes extended-query COPY IN and returns to the building loop.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C> Conn<S, ServerCopyInFailed<CopySimple>, C>

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerSimpleError, C>, Frame)>

Reports a client COPY failure before simple-query readiness.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerCopyInFailed<CopyExtended>, C>

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Reports a client COPY failure and discards the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C, Resume> Conn<S, ServerCopyOut<Resume>, C>

pub fn data(self, data: Bytes) -> Result<(Self, Frame)>

Sends one COPY OUT data chunk and remains in the nested session.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn replication(self, message: &BackendReplication) -> Result<(Self, Frame)>

Sends a structured WAL or keepalive payload.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn done(self) -> CopyOutCompletion<S, C, Resume>

Ends the COPY data stream before its command completion.

Errors

Returns an error only if the fixed response cannot be encoded.

impl<S, C> Conn<S, ServerCopyOutDone<CopySimple>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerSimpleQuery, C>, Frame)>

Completes simple-query COPY OUT before ReadyForQuery.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C> Conn<S, ServerCopyOutDone<CopyExtended>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Completes extended-query COPY OUT and returns to the building loop.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C, Resume: CopyResume> Conn<S, ServerCopyBoth<Resume, BothOpen>, C>

pub fn offer_frontend( self, message: FrontendMessage, ) -> CopyBothOpenProjection<S, C, Resume>

Projects client data, half-close, or failure while both directions are open.

Errors

Returns the unchanged state and message if it is not COPY traffic.

pub fn data(self, data: Bytes) -> Result<(Self, Frame)>

Sends backend COPY data while its direction remains open.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn replication(self, message: &BackendReplication) -> Result<(Self, Frame)>

Sends a structured WAL or keepalive payload while both halves are open.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn done(self) -> CopyBothServerHalfClose<S, C, Resume>

Half-closes the backend direction while the client direction remains open.

Errors

Returns an error only if the fixed completion frame cannot be encoded.

impl<S, C, Resume> Conn<S, ServerCopyBoth<Resume, BothClientDone>, C>

pub fn data(self, data: Bytes) -> Result<(Self, Frame)>

Sends remaining backend data after the client has half-closed.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn replication(self, message: &BackendReplication) -> Result<(Self, Frame)>

Sends a structured WAL or keepalive payload after the client half-close.

Errors

Returns an error only if the data frame cannot be encoded.

pub fn done(self) -> CopyBothCompletion<S, C, Resume>

Half-closes the backend direction, completing both COPY streams.

Errors

Returns an error only if the fixed completion frame cannot be encoded.

impl<S, C, Resume: CopyResume> Conn<S, ServerCopyBoth<Resume, BothServerDone>, C>

pub fn offer_frontend( self, message: FrontendMessage, ) -> CopyBothServerDoneProjection<S, C, Resume>

Projects remaining client traffic after the backend has half-closed.

Errors

Returns the unchanged state and message if it is not COPY traffic.

impl<S, C> Conn<S, ServerCopyBoth<CopySimple, BothDone>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerSimpleQuery, C>, Frame)>

Completes simple-query COPY BOTH before ReadyForQuery.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C> Conn<S, ServerCopyBoth<CopyExtended, BothDone>, C>

pub fn command_complete( self, tag: Bytes, ) -> Result<(Conn<S, ServerBuilding, C>, Frame)>

Completes extended-query COPY BOTH and returns to the building loop.

Errors

Returns an error if the command tag contains a NUL byte.

impl<S, C> Conn<S, ServerCopyBothFailed<CopySimple>, C>

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerSimpleError, C>, Frame)>

Reports a client COPY failure before simple-query readiness.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerCopyBothFailed<CopyExtended>, C>

pub fn error( self, response: DiagnosticResponse, ) -> Result<(Conn<S, ServerExtendedError, C>, Frame)>

Reports a client COPY failure and discards the pipeline until Sync.

Errors

Returns an error if a diagnostic field is invalid.

impl<S, C> Conn<S, ServerExtendedError, C>

pub fn discard(self, message: &FrontendMessage) -> ServerDiscard<S, C>

Discards one pipelined message; only Sync exits error recovery.

impl<S, C> Conn<S, ServerSync, C>

pub fn ready( self, status: TransactionStatus, ) -> Result<(ServerReadyState<S, C>, Frame)>

Answers Sync with ReadyForQuery and surfaces transaction status.

Errors

Returns an error only if the fixed ready message cannot be encoded.

impl<S, C> Conn<S, Ready, C>

pub fn push_terminate(self) -> (Conn<S, Terminated, C>, Frame)

Gracefully terminates a ready session without waiting for a backend reply.

pub fn push_query( self, query: &[u8], ) -> Result<(Conn<S, SimpleQuery, Dirty>, Frame)>

Buffers a simple query and conservatively taints the pooled session.

Simple-query text can create resources which are not reflected in ParameterStatus, including listeners, prepared statements, and advisory locks. Use Self::push_stateless_query only after custom SQL inspection has established that the command cannot retain session state.

Errors

Returns an error if the query contains a NUL byte.

pub fn push_stateless_query( self, query: &[u8], ) -> Result<(Conn<S, SimpleQuery, C>, Frame)>

Buffers query text which the caller has proved leaves no session state.

Errors

Returns an error if the query contains a NUL byte.

pub fn push_function_call( self, message: &FunctionCall, ) -> Result<(Conn<S, FunctionCalling, Dirty>, Frame)>

Buffers the deprecated function-call protocol message as a typed exchange.

Errors

Returns an error if a count or argument length exceeds its wire field.

pub fn push_stateless_function_call( self, message: &FunctionCall, ) -> Result<(Conn<S, FunctionCalling, C>, Frame)>

Buffers an allow-listed function call known not to retain session state.

Errors

Returns an error if a count or argument length exceeds its wire field.

pub fn begin_extended(self) -> Conn<S, Building, C>

Begins extended-query construction and consumes the ready connection.

use pg_proto::{Conn, auth::Ready};
fn use_after_transition<S, C>(conn: Conn<S, Ready, C>) {
    let _building = conn.begin_extended();
    let _again = conn.begin_extended();
}

impl<S, C> Conn<S, FunctionCalling, C>

pub fn offer( self, message: BackendMessage, ) -> Result<FunctionCallTransition<S, C>, (Self, BackendMessage)>

Accepts exactly the function result or an error, after which readiness must still be consumed.

Errors

Returns the unchanged connection and message for an illegal response.

impl<S> Conn<S, Ready, Pristine>

pub fn release(self) -> S

Releases only a statically pristine, ready connection to a pool.

use pg_proto::{Conn, Dirty, auth::Ready};
fn cannot_release<S>(conn: Conn<S, Ready, Dirty>) {
    let _transport = conn.release();
}

impl<S> Conn<S, Ready, Dirty>

pub fn begin_reset(self) -> Result<(Conn<S, Resetting, Dirty>, Frame)>

Begins the only typed path which can recover pool-safe cleanliness.

ROLLBACK makes the sequence legal after either transaction status; DISCARD ALL then clears session-local resources and settings.

Errors

Returns an error only if the fixed reset query cannot be encoded.

impl<S, C> Conn<S, Building, C>

pub fn push_parse( self, message: &Parse, ) -> Result<(Conn<S, Building, Dirty>, Frame)>

Parse is a self-loop while constructing an extended-query pipeline.

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_describe(self, message: &Describe) -> Result<(Self, Frame)>

Describe is a self-loop while constructing an extended-query pipeline.

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_bind( self, message: &Bind, ) -> Result<(Conn<S, BoundBuilding, Dirty>, Frame)>

Bind introduces an executable portal.

Execute is not available before this transition:

use bytes::Bytes;
use pg_proto::{Conn, session::Building};
fn execute_without_bind<S, C>(conn: Conn<S, Building, C>) {
    let _ = conn.push_execute(Bytes::new());
}

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_close(self, message: &Close) -> Result<(Self, Frame)>

Close is legal while building, but does not make a portal executable.

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_flush(self) -> (Self, Frame)

Requests delivery of buffered extended-query responses without ending the cycle.

pub fn push_sync(self) -> (Conn<S, AwaitingReady, C>, Frame)

Ends the extended-query pipeline and waits for readiness.

impl<S, C> Conn<S, BoundBuilding, C>

pub fn push_parse( self, message: &Parse, ) -> Result<(Conn<S, BoundBuilding, Dirty>, Frame)>

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_bind( self, message: &Bind, ) -> Result<(Conn<S, BoundBuilding, Dirty>, Frame)>

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_describe(self, message: &Describe) -> Result<(Self, Frame)>

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_execute(self, message: &Execute) -> Result<(Self, Frame)>

Execute is unavailable until a Bind transition has occurred.

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_close(self, message: &Close) -> Result<(Self, Frame)>

Errors

Returns an error if the structured message cannot be reconstructed.

pub fn push_flush(self) -> (Self, Frame)

Requests delivery of buffered extended-query responses without ending the cycle.

pub fn push_sync(self) -> (Conn<S, AwaitingReady, C>, Frame)

Ends the extended-query pipeline and waits for readiness.

impl<S, C> Conn<S, SimpleQuery, C>

pub fn offer( self, item: SessionItem, ) -> Result<SimpleTransition<S, C>, (Self, SessionItem)>

Advances a simple-query session using an actual projected backend item.

Errors

Returns the unchanged connection and item if it is illegal in this phase.

impl<S, C> Conn<S, CopyIn, C>

pub fn push_copy_data(self, data: Bytes) -> (Self, Frame)

Query is unavailable in this nested COPY session.

use pg_proto::{Conn, session::CopyIn};
fn query_during_copy<S, C>(conn: Conn<S, CopyIn, C>) {
    let _ = conn.push_query(b"select 1");
}

pub fn push_copy_done(self) -> (Conn<S, AwaitingReady, C>, Frame)

Closes the client-to-backend copy stream and waits for command completion.

pub fn push_copy_fail( self, message: &[u8], ) -> Result<(Conn<S, AwaitingReady, C>, Frame)>

Aborts COPY IN with a frontend error string.

Errors

Returns an error if the message contains a NUL byte.

pub fn offer( self, item: SessionItem, ) -> Result<CopyInTransition<S, C>, (Self, SessionItem)>

Projects an asynchronous backend failure while COPY IN data is being sent.

This branch is reachable after cancellation or an early server-side COPY failure. Non-error messages leave the COPY IN connection unchanged.

Errors

Returns the live connection and item when it is not an error response.

impl<S, C> Conn<S, CopyBothClientDone, C>

pub fn offer( self, item: SessionItem, ) -> Result<CopyBothClientDoneReceive<S, C>, (Self, SessionItem)>

Continues receiving after the frontend half has closed.

Errors

Returns the unchanged connection and item for an illegal response.

impl<S, C> Conn<S, CopyBothServerDone, C>

pub fn push_copy_data(self, data: Bytes) -> (Self, Frame)

Continues sending after the backend half has closed.

pub fn push_replication(self, message: &FrontendReplication) -> (Self, Frame)

Sends a structured standby message after the backend half-close.

pub fn push_copy_done(self) -> (Conn<S, AwaitingReady, C>, Frame)

Closes the remaining frontend half and begins readiness processing.

impl<S, C> Conn<S, CopyOut, C>

pub fn offer( self, item: SessionItem, ) -> Result<CopyOutTransition<S, C>, (Self, SessionItem)>

Advances COPY OUT using backend evidence.

Errors

Returns the unchanged connection and item when it is illegal in COPY OUT.

impl<S, C> Conn<S, CopyBoth, C>

pub fn push_copy_data(self, data: Bytes) -> (Self, Frame)

Sends one opaque data chunk while retaining both COPY directions.

pub fn push_replication(self, message: &FrontendReplication) -> (Self, Frame)

Sends a structured standby message in the walsender stream.

pub fn push_copy_done(self) -> (Conn<S, CopyBothClientDone, C>, Frame)

Closes the client half while leaving the backend half readable.

pub fn offer( self, item: SessionItem, ) -> Result<CopyBothReceive<S, C>, (Self, SessionItem)>

Receives the backend half of a bidirectional COPY session.

Errors

Returns the unchanged connection and item when it is illegal in COPY BOTH.

impl<S, C> Conn<S, Draining, C>

pub fn offer(self, item: SessionItem) -> DrainingTransition<S, C>

ReadyForQuery is the sole exit from error draining.

impl<S, C> Conn<S, AwaitingReady, C>

pub fn offer(self, item: SessionItem) -> AwaitingReadyTransition<S, C>

Consumes responses after Sync until ReadyForQuery proves readiness.

impl<S> Conn<S, Resetting, Dirty>

pub fn offer(self, item: SessionItem) -> ResettingTransition<S>

Waits for evidence that DISCARD ALL itself completed.

impl<S> Conn<S, ResetComplete, Dirty>

pub fn offer(self, item: SessionItem) -> ResetCompleteTransition<S>

Restores Pristine only from idle readiness and the startup parameter baseline.

impl<S, P> Conn<S, P, Pristine>

pub fn mark_dirty(self) -> Conn<S, P, Dirty>

Conservatively records session-local state without changing protocol phase.

impl<S, D, Phase, Cleanliness> Conn<Buffered<S, D>, Phase, Cleanliness>

pub fn push_frame(&mut self, frame: Frame) -> Result<()>

Adds an already-typed message to this connection’s outbound buffer.

Errors

Returns an error when the frame is too large to encode.

pub fn pending_output(&self) -> &[u8]

Returns encoded output which has not yet been flushed.

impl<S, Cleanliness> Conn<Buffered<S, Backend>, PreStartup, Cleanliness>

pub fn request_ssl( self, ) -> Conn<Buffered<S, Backend>, AwaitingSslReply, Cleanliness>

Buffers an SSLRequest and enters the raw single-byte reply phase.

pub fn request_gss( self, ) -> Conn<Buffered<S, Backend>, AwaitingGssReply, Cleanliness>

Buffers a GSSENCRequest and enters the raw single-byte reply phase.

impl<S, Cleanliness> Conn<Buffered<S, Frontend>, ServerSslDecision, Cleanliness>

pub fn approve_ssl( self, ) -> Conn<Buffered<S, Frontend>, TlsHandshake, Cleanliness>

Buffers the server’s raw S response and enters the TLS handshake phase.

pub fn decline_ssl(self) -> Conn<Buffered<S, Frontend>, PreStartup, Cleanliness>

Buffers the server’s raw N response and returns to pre-startup choice.

pub fn reject_ssl_with_legacy_error( self, ) -> Conn<Buffered<S, Frontend>, Terminated, Cleanliness>

Buffers the historical raw E response and terminates negotiation.

impl<S, Cleanliness> Conn<Buffered<S, Frontend>, ServerGssDecision, Cleanliness>

pub fn approve_gss( self, ) -> Conn<Buffered<S, Frontend>, GssHandshake, Cleanliness>

Buffers the server’s raw S response and enters the GSS handshake phase.

pub fn decline_gss(self) -> Conn<Buffered<S, Frontend>, PreStartup, Cleanliness>

Buffers the server’s raw N response and returns to pre-startup choice.

pub fn reject_gss_with_legacy_error( self, ) -> Conn<Buffered<S, Frontend>, Terminated, Cleanliness>

Buffers the historical raw E response and terminates negotiation.

impl<S: AsyncRead + Unpin, Cleanliness> Conn<Buffered<S, Backend>, AwaitingSslReply, Cleanliness>

pub async fn receive_ssl_reply( self, ) -> Result<Negotiation<Buffered<S, Backend>, TlsHandshake, Cleanliness>>

Receives and projects the server’s raw SSL decision byte.

Errors

Returns an I/O error or rejects a byte other than S, N, or E.

pub async fn receive_ssl_reply_for_mode( self, mode: SslMode, ) -> Result<SslModeNegotiation<Buffered<S, Backend>, Cleanliness>>

Receives the server decision and enforces the selected plaintext fallback policy.

Errors

Returns an I/O error or rejects a byte other than S, N, or E.

impl<S: AsyncRead + Unpin, Cleanliness> Conn<Buffered<S, Backend>, AwaitingGssReply, Cleanliness>

pub async fn receive_gss_reply( self, ) -> Result<Negotiation<Buffered<S, Backend>, GssHandshake, Cleanliness>>

Receives and projects the server’s raw GSSENC decision byte.

Errors

Returns an I/O error or rejects a byte other than S, N, or E.

impl<S, Cleanliness> Conn<Buffered<S, Backend>, TlsHandshake, Cleanliness>

where S: AsyncRead + AsyncWrite + Unpin,

pub async fn connect_tls( self, server_name: ServerName<'static>, config: Arc<ClientConfig>, ) -> Result<Conn<Buffered<ClientTls<S>, Backend>, PreStartup, Cleanliness>>

Completes a client-side TLS handshake and changes the transport type.

Errors

Returns a TLS handshake, certificate, channel-binding, or buffer-state error.

impl<S, Cleanliness> Conn<Buffered<S, Frontend>, TlsHandshake, Cleanliness>

where S: AsyncRead + AsyncWrite + Unpin,

pub async fn accept_tls( self, config: Arc<ServerConfig>, leaf_certificate: CertificateDer<'static>, ) -> Result<Conn<Buffered<ServerTls<S>, Frontend>, PreStartup, Cleanliness>>

Completes a server-side TLS handshake and changes the transport type.

Errors

Returns a TLS handshake, certificate, channel-binding, or buffer-state error.

impl<S, D, Cleanliness> Conn<Buffered<S, D>, Startup, Cleanliness>

pub fn push_startup_packet(&mut self, packet: &[u8])

Buffers the raw, untagged startup packet before normal framing begins.

impl<S: AsyncWrite + Unpin, D, Phase, Cleanliness> Conn<Buffered<S, D>, Phase, Cleanliness>

pub async fn flush(&mut self) -> Result<()>

Flushes buffered output while retaining ownership of the typed connection.

Errors

Returns an error from the underlying transport.

impl<S: AsyncRead + Unpin, Phase, Cleanliness> Conn<Buffered<S, Backend>, Phase, Cleanliness>

pub async fn receive_backend_wire(&mut self) -> Result<BackendMessage>

Receives one backend message before demultiplexing or state advancement. This is the interception point for proxy policy and message rewriting.

Errors

Returns decoding and underlying transport read errors, or UnexpectedEof.

pub fn project_backend( &mut self, message: BackendMessage, ) -> Option<SessionItem>

Projects an inspected or modified message into the filtered session stream.

pub async fn receive(&mut self) -> Result<SessionItem>

Receives the next message in the filtered session projection.

Errors

Returns decoding and underlying transport read errors, or UnexpectedEof.

pub fn cancel_key(&self) -> Option<&CancelKey>

Returns the latest upstream cancellation key observed during startup.

pub fn parameters(&self) -> &BTreeMap<Bytes, Bytes>

Returns the latest backend parameter values observed by the demux.

pub fn parameters_changed(&self) -> bool

Returns whether current parameters differ from the startup baseline.

pub fn transaction_status(&self) -> Option<TransactionStatus>

Returns the latest transaction status observed in ReadyForQuery.

pub fn pop_notification(&mut self) -> Option<Notification>

Removes the oldest queued asynchronous notification.

pub fn pop_notice(&mut self) -> Option<TaggedNotice>

Removes the next tagged notice for prompt forwarding to the client.

pub fn pop_parameter_status(&mut self) -> Option<ParameterStatus>

Removes the next ordered parameter update for forwarding to the client.

pub fn pop_async_event(&mut self) -> Option<OrderedAsyncEvent>

Removes the next independent backend event in original wire order.

impl<S: AsyncRead + Unpin, Phase, Cleanliness> Conn<Buffered<S, Frontend>, Phase, Cleanliness>

pub async fn receive_frontend_wire(&mut self) -> Result<FrontendMessage>

Receives one frontend message before any server-role state advancement.

Errors

Returns decoding and underlying transport read errors, or UnexpectedEof.

impl<S: AsyncRead + Unpin, Cleanliness> Conn<Buffered<S, Frontend>, PreStartup, Cleanliness>

pub async fn receive_pre_startup_wire(&mut self) -> Result<PreStartupMessage>

Receives a raw pre-startup packet before server-role state projection.

Errors

Returns malformed pre-startup data and underlying transport read errors.

impl<Transport, Phase, Cleanliness> Conn<Transport, Phase, Cleanliness>

pub fn into_transport(self) -> Transport

Returns the underlying transport when deliberately leaving the typed API.

Panics

Panics only if an internal transition has already moved the transport.

pub fn map_transport<Next>( self, map: impl FnOnce(Transport) -> Next, ) -> Conn<Next, Phase, Cleanliness>

Changes transport representation without changing either state index.

Panics

Panics only if an internal transition has already moved the transport.

impl<Transport> Conn<Transport, PreStartup, Pristine>

pub const fn new(transport: Transport) -> Self

Starts a new connection before any startup packet has been sent.

Trait Implementations

impl<Transport: Debug, Phase: Debug, Cleanliness: Debug> Debug for Conn<Transport, Phase, Cleanliness>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Transport, Phase, Cleanliness> Drop for Conn<Transport, Phase, Cleanliness>

Available on debug-assertions enabled only.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.