Skip to main content

halephant_core/proxy/
frontend.rs

1//! Per-client wire-protocol entry point. Drives the PostgreSQL
2//! startup handshake (SSL/GSS negotiation, `StartupMessage` parsing,
3//! cancel forwarding), authenticates, checks out an initial server
4//! connection, sets up multiplexed LISTEN when configured, and
5//! dispatches to [`crate::proxy::session::forward`] or
6//! [`crate::proxy::transaction::forward`] based on the pool mode.
7
8use std::net::SocketAddr;
9use std::sync::Arc;
10
11use futures_util::{SinkExt, StreamExt};
12use tokio::io::AsyncWriteExt;
13use tokio::net::TcpStream;
14use tokio_util::codec::Framed;
15use tracing::{Instrument, info_span, trace};
16
17use crate::auth::Authenticator;
18use crate::clients::{self, ClientRegistry, ClientState};
19use crate::config::Config;
20use crate::config::cluster::pool::{ListenMode, PoolMode};
21use crate::listener::ListenerManager;
22use crate::pool::{PoolManager, Routing};
23use crate::proto::codec::{BackendCodec, FrontendCodec};
24use crate::proto::frontend::FrontendMessage;
25use crate::proxy;
26
27/// Accept a client connection, run the PostgreSQL startup handshake,
28/// authenticate, and forward traffic until the client disconnects.
29/// Wraps the whole session in the root `proxy.client` span so every
30/// nested span (setup, auth, checkout, transaction, statement) appears
31/// under a single trace from accept through cleanup.
32pub async fn forward(
33    client_stream: TcpStream,
34    client_addr: SocketAddr,
35    config: &Config,
36    pools: &Arc<PoolManager>,
37    listeners: &ListenerManager,
38    auth: &Authenticator,
39    clients: &Arc<ClientRegistry>,
40) -> anyhow::Result<()> {
41    let client_guard = clients.register(client_addr);
42    let client_id = client_guard.id();
43
44    // Root span for the entire client session. Every subsequent span
45    // (proxy.setup, auth, pool.checkout, pool.connect, proxy.session,
46    // proxy.transaction, proxy.statement, ...) nests under this one so a
47    // single trace covers accept → cleanup for a client. `db.namespace`
48    // and `user` start empty; they're recorded once parsed from the
49    // startup message.
50    let client_span = info_span!(
51        "proxy.client",
52        halephant.client.id = client_id.as_u64(),
53        client.address = %client_addr,
54        db.namespace = tracing::field::Empty,
55        user = tracing::field::Empty,
56        otel.status_code = tracing::field::Empty,
57        otel.status_description = tracing::field::Empty,
58    );
59
60    async move {
61        let result = forward_inner(
62            client_stream,
63            client_addr,
64            config,
65            pools,
66            listeners,
67            auth,
68            &client_guard,
69        )
70        .await;
71        let span = tracing::Span::current();
72        match &result {
73            Ok(()) => {
74                span.record("otel.status_code", "OK");
75            }
76            Err(e) => {
77                span.record("otel.status_code", "ERROR");
78                span.record("otel.status_description", e.to_string().as_str());
79            }
80        }
81        // `client_guard` dropped here — entry removed from the registry.
82        result
83    }
84    .instrument(client_span)
85    .await
86}
87
88async fn forward_inner(
89    client_stream: TcpStream,
90    client_addr: SocketAddr,
91    config: &Config,
92    pools: &Arc<PoolManager>,
93    listeners: &ListenerManager,
94    auth: &Authenticator,
95    client_guard: &clients::ClientGuard,
96) -> anyhow::Result<()> {
97    let mut client = Framed::new(client_stream, FrontendCodec::new());
98
99    // Phase 1: SSL/GSS negotiation -> read StartupMessage.
100    let startup = loop {
101        match client.next().await.transpose()? {
102            Some(FrontendMessage::SslRequest) => {
103                trace!("responding N to SSLRequest");
104                client.get_mut().write_all(b"N").await?;
105            }
106            Some(FrontendMessage::GssEncRequest) => {
107                trace!("responding N to GssEncRequest");
108                client.get_mut().write_all(b"N").await?;
109            }
110            Some(FrontendMessage::CancelRequest {
111                process_id,
112                secret_key,
113            }) => {
114                return forward_cancel(config, process_id, secret_key).await;
115            }
116            Some(FrontendMessage::Startup(s)) => break s,
117            Some(other) => anyhow::bail!("unexpected message during startup: {other:?}"),
118            None => return Ok(()),
119        }
120    };
121
122    let database = startup_param(&startup.parameters, "database");
123    let user = startup_param(&startup.parameters, "user");
124
125    // Log client-supplied startup parameters that halephant does not
126    // forward. In transaction mode, server connections are shared so
127    // per-client startup parameters (options, application_name, etc.)
128    // cannot be forwarded — they would leak to the next client. These
129    // must be configured in the TOML per-user instead.
130    for (key, value) in &startup.parameters {
131        if key != "database" && key != "user" {
132            trace!(%database, %user, param = %key, %value, "ignoring client startup parameter");
133        }
134    }
135
136    // Record the client's identity on both the registry entry and the
137    // enclosing `proxy.client` span now that it's known.
138    client_guard.set_database_and_user(&database, &user);
139    client_guard.set_state(ClientState::Authenticating);
140    {
141        let span = tracing::Span::current();
142        span.record("db.namespace", database.as_str());
143        span.record("user", user.as_str());
144    }
145
146    let mode = config
147        .find_pool(&database)
148        .map_or_default(|(_, _, p)| p.mode);
149    let read_only = config
150        .find_user(&database, &user)
151        .is_some_and(crate::config::cluster::pool::user::UserConfig::is_read_only);
152    trace!(%database, %user, ?mode, read_only, "client startup");
153
154    // Phase 2-3: Authenticate, check out a server connection, and send
155    // post-auth startup messages. Wrapped in a short-lived span so auth and
156    // the initial checkout appear as a single trace without orphaned children.
157    let mut guard = async {
158        let result: anyhow::Result<_> = async {
159            let (_, cluster, _) = config
160                .find_pool(&database)
161                .ok_or_else(|| anyhow::anyhow!("database {database:?} not configured"))?;
162            let admin_addr = pools.resolve(&database, Routing::Primary)?;
163            let admin_password = pools
164                .pgpass()
165                .lookup_addr(&admin_addr, &cluster.admin_database, &cluster.admin_user)
166                .map(str::to_owned);
167            if admin_password.is_none() {
168                trace!(
169                    %database,
170                    admin_user = %cluster.admin_user,
171                    admin_database = %cluster.admin_database,
172                    %admin_addr,
173                    "no .pgpass entry for admin connection (upstream may use trust auth)"
174                );
175            }
176            auth.authenticate(
177                &mut client,
178                &database,
179                &user,
180                config,
181                &admin_addr,
182                admin_password.as_deref(),
183            )
184            .await
185            .map_err(|e| anyhow::anyhow!("authentication failed: {e}"))?;
186            let mut guard = pools
187                .checkout(client_guard, &database, &user, read_only)
188                .await?;
189            crate::messages::send_post_auth_startup(&mut client, guard.conn()).await?;
190            Ok(guard)
191        }
192        .await;
193        let span = tracing::Span::current();
194        match &result {
195            Ok(_) => {
196                span.record("otel.status_code", "OK");
197            }
198            Err(e) => {
199                span.record("otel.status_code", "ERROR");
200                span.record("otel.status_description", e.to_string().as_str());
201            }
202        }
203        result
204    }
205    .instrument(info_span!(
206        "proxy.setup",
207        client.address = %client_addr,
208        db.namespace = %database,
209        user = %user,
210        otel.status_code = tracing::field::Empty,
211        otel.status_description = tracing::field::Empty,
212    ))
213    .await?;
214
215    // Auth + initial checkout done — the client is now connected and
216    // ready. Phase 2 will flip to `InTransaction` / `Waiting` during
217    // forward and checkout respectively.
218    client_guard.set_state(ClientState::Idle);
219
220    // Phase 4: Set up multiplexed LISTEN if configured.
221    let listen_mode = config
222        .find_pool(&database)
223        .and_then(|(_, _, p)| p.listen_mode)
224        .unwrap_or_default();
225    let mut notifications = if listen_mode == ListenMode::Multiplex {
226        Some(listeners.subscribe(&database, &user))
227    } else {
228        None
229    };
230
231    // Phase 5: Forward based on pool mode.
232    match mode {
233        PoolMode::Session => {
234            let node = guard.node().to_owned();
235            // Session mode holds the backend for the entire client
236            // lifetime — reflect that in the registry as InTransaction
237            // (which stands in for "actively holding a backend").
238            client_guard.set_state(ClientState::InTransaction);
239            async {
240                let result = proxy::session::forward(&mut client, guard.conn(), pools).await;
241                let span = tracing::Span::current();
242                match &result {
243                    Ok(()) => {
244                        span.record("otel.status_code", "OK");
245                    }
246                    Err(e) => {
247                        span.record("otel.status_code", "ERROR");
248                        span.record("otel.status_description", e.to_string().as_str());
249                    }
250                }
251                if result.is_ok() {
252                    guard.checkin();
253                }
254                result
255            }
256            .instrument(info_span!(
257                "proxy.session",
258                client.address = %client_addr,
259                db.namespace = %database,
260                user = %user,
261                server.address = node.as_str(),
262                otel.status_code = tracing::field::Empty,
263                otel.status_description = tracing::field::Empty,
264            ))
265            .await
266        }
267        PoolMode::Transaction => {
268            guard.checkin();
269            proxy::transaction::forward(
270                &mut client,
271                pools,
272                client_guard,
273                &mut notifications,
274                listen_mode,
275                &database,
276                &user,
277                read_only,
278                config.otel.query_text,
279            )
280            .await
281        }
282    }
283}
284
285/// Forward a cancel request to every node in every configured cluster.
286/// Only the server that owns the `(pid, secret_key)` pair will act on
287/// it; everything else discards.
288///
289/// Fans every delivery out in parallel and caps each individual
290/// connect at 500 ms. Cancels are time-sensitive — without the
291/// timeout an unreachable node blocks on the OS TCP connect budget
292/// (75–127 s on Linux); without the parallelism, N down nodes stack
293/// those delays sequentially and push the cancel past the point a
294/// user would notice.
295async fn forward_cancel(config: &Config, process_id: i32, secret_key: i32) -> anyhow::Result<()> {
296    const CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(500);
297
298    trace!(process_id, secret_key, "forwarding cancel request");
299    let mut tasks = tokio::task::JoinSet::new();
300    for cluster in config.cluster.values() {
301        for addr in &cluster.nodes {
302            let addr = addr.clone();
303            tasks.spawn(async move {
304                let Ok(Ok(upstream)) =
305                    tokio::time::timeout(CONNECT_TIMEOUT, TcpStream::connect(addr.as_str())).await
306                else {
307                    return;
308                };
309                let mut server = Framed::new(upstream, BackendCodec::new());
310                let _ = server
311                    .send(FrontendMessage::CancelRequest {
312                        process_id,
313                        secret_key,
314                    })
315                    .await;
316            });
317        }
318    }
319    // Drain the JoinSet so the function doesn't return before the
320    // deliveries complete — the caller is the client's own connection
321    // handler, which exits immediately after, and the tokio runtime
322    // would cancel pending futures on task drop.
323    while tasks.join_next().await.is_some() {}
324    Ok(())
325}
326
327fn startup_param(params: &[(String, String)], key: &str) -> String {
328    params
329        .iter()
330        .find(|(k, _)| k == key)
331        .map_or_default(|(_, v)| v.clone())
332}