Skip to main content

littlegraph_query_api/
server.rs

1use std::net::SocketAddr;
2use std::sync::Arc;
3use std::time::Duration;
4
5use axum::body::Bytes;
6use axum::extract::{DefaultBodyLimit, Path, State};
7use axum::http::{header, HeaderMap, StatusCode};
8use axum::middleware::{self, Next};
9use axum::response::Response;
10use axum::routing::post;
11use axum::{extract::Request, Router};
12use axum_server::tls_rustls::{RustlsAcceptor, RustlsConfig};
13use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
14use base64::Engine;
15use littlegraph_core::{CancellationToken as CoreCancellationToken, Graph};
16use tokio::sync::{OwnedSemaphorePermit, Semaphore};
17
18use crate::database::auto_commit;
19use crate::error::{HttpError, QueryApiError, Result};
20use crate::request::QueryRequest;
21use crate::response::{QueryResponse, ResponseFormat};
22use crate::transaction::TransactionManager;
23use crate::{AuthContext, CancellationToken, QueryApiAuth, QueryApiServerConfig};
24
25const ROOT: &str = "/db/self/query/v2";
26
27#[derive(Clone)]
28struct AppState {
29    config: Arc<QueryApiServerConfig>,
30    transactions: TransactionManager,
31    requests: Arc<Semaphore>,
32    query_cancellation: CoreCancellationToken,
33}
34
35/// A bound Neo4j Query API listener.
36pub struct QueryApiServer {
37    listener: std::net::TcpListener,
38    state: AppState,
39    tls: Option<RustlsConfig>,
40}
41
42impl QueryApiServer {
43    /// Validate database and TLS access and bind the configured listener.
44    pub async fn bind(config: QueryApiServerConfig) -> Result<Self> {
45        config.validate()?;
46        let database_path = config.database_path.clone();
47        tokio::task::spawn_blocking(move || Graph::open_neo4j_writable(database_path))
48            .await
49            .map_err(|error| QueryApiError::Database(format!("validation task failed: {error}")))?
50            .map_err(|error| QueryApiError::Database(error.to_string()))?;
51
52        let tls = match &config.tls {
53            Some(tls) => {
54                let mut certificates =
55                    tokio::fs::read(&tls.certificate_file)
56                        .await
57                        .map_err(|error| {
58                            QueryApiError::InvalidConfiguration(format!(
59                                "failed to read TLS certificate file {}: {error}",
60                                tls.certificate_file.display()
61                            ))
62                        })?;
63                if let Some(ca_file) = &tls.ca_file {
64                    let ca = tokio::fs::read(ca_file).await.map_err(|error| {
65                        QueryApiError::InvalidConfiguration(format!(
66                            "failed to read TLS CA file {}: {error}",
67                            ca_file.display()
68                        ))
69                    })?;
70                    certificates.push(b'\n');
71                    certificates.extend(ca);
72                }
73                let key = tokio::fs::read(&tls.certificate_file)
74                    .await
75                    .map_err(|error| {
76                        QueryApiError::InvalidConfiguration(format!(
77                            "failed to read TLS private key file {}: {error}",
78                            tls.certificate_file.display()
79                        ))
80                    })?;
81                Some(
82                    RustlsConfig::from_pem(certificates, key)
83                        .await
84                        .map_err(|error| {
85                            QueryApiError::InvalidConfiguration(format!(
86                                "failed to load Query API TLS configuration: {error}"
87                            ))
88                        })?,
89                )
90            }
91            None => None,
92        };
93
94        let listener = std::net::TcpListener::bind(config.listen_addr)?;
95        listener.set_nonblocking(true)?;
96        let config = Arc::new(config);
97        let state = AppState {
98            transactions: TransactionManager::new(
99                config.database_path.clone(),
100                config.limits.clone(),
101            ),
102            requests: Arc::new(Semaphore::new(config.limits.max_concurrent_requests)),
103            query_cancellation: CoreCancellationToken::new(),
104            config,
105        };
106        Ok(Self {
107            listener,
108            state,
109            tls,
110        })
111    }
112
113    /// Return the actual bound address, including an assigned port for port zero.
114    pub fn local_addr(&self) -> Result<SocketAddr> {
115        Ok(self.listener.local_addr()?)
116    }
117
118    /// Serve HTTP requests until cancellation and then roll back open transactions.
119    pub async fn serve(self, shutdown: CancellationToken) -> Result<()> {
120        let body_limit = self.state.config.limits.max_request_bytes;
121        let router = Router::new()
122            .route(ROOT, post(execute))
123            .route(&format!("{ROOT}/tx"), post(begin_transaction))
124            .route(
125                &format!("{ROOT}/tx/:tx_id"),
126                post(continue_transaction).delete(rollback_transaction),
127            )
128            .route(
129                &format!("{ROOT}/tx/:tx_id/commit"),
130                post(commit_transaction),
131            )
132            .fallback(route_not_found)
133            .layer(DefaultBodyLimit::max(body_limit))
134            .layer(middleware::from_fn_with_state(
135                self.state.clone(),
136                authenticate_request,
137            ))
138            .with_state(self.state.clone());
139
140        let handle = axum_server::Handle::new();
141        let shutdown_handle = handle.clone();
142        let shutdown_signal = shutdown.clone();
143        let query_cancellation = self.state.query_cancellation.clone();
144        let grace = self.state.config.limits.shutdown_grace_period;
145        let shutdown_task = tokio::spawn(async move {
146            shutdown_signal.cancelled().await;
147            query_cancellation.cancel();
148            shutdown_handle.graceful_shutdown(Some(grace));
149        });
150
151        let cleanup_manager = self.state.transactions.clone();
152        let cleanup_shutdown = shutdown.clone();
153        let cleanup_task = tokio::spawn(async move {
154            let mut interval = tokio::time::interval(Duration::from_secs(1));
155            loop {
156                tokio::select! {
157                    _ = cleanup_shutdown.cancelled() => break,
158                    _ = interval.tick() => cleanup_manager.expire().await,
159                }
160            }
161        });
162
163        let result = if let Some(tls) = self.tls {
164            let acceptor = RustlsAcceptor::new(tls)
165                .handshake_timeout(self.state.config.limits.tls_handshake_timeout);
166            axum_server::from_tcp(self.listener)
167                .acceptor(acceptor)
168                .handle(handle)
169                .serve(router.into_make_service())
170                .await
171        } else {
172            axum_server::from_tcp(self.listener)
173                .handle(handle)
174                .serve(router.into_make_service())
175                .await
176        };
177        cleanup_task.abort();
178        shutdown_task.abort();
179        self.state.query_cancellation.cancel();
180        if tokio::time::timeout(grace, self.state.transactions.shutdown())
181            .await
182            .is_err()
183        {
184            log::warn!("Query API transaction cleanup exceeded the shutdown grace period");
185        }
186        result.map_err(|error| QueryApiError::Http(error.to_string()))
187    }
188}
189
190async fn execute(State(state): State<AppState>, headers: HeaderMap, body: Bytes) -> Response {
191    let error_format = ResponseFormat::for_error(&headers);
192    handle_execute(state, &headers, &body)
193        .await
194        .unwrap_or_else(|error| error_format.render_error(error))
195}
196
197async fn handle_execute(
198    state: AppState,
199    headers: &HeaderMap,
200    body: &[u8],
201) -> std::result::Result<Response, HttpError> {
202    let _permit = admit(&state).await?;
203    let (request, format, auth) = parse_request(&state, headers, body)?;
204    let statement = request.statement_required()?.to_owned();
205    let params = request.params()?;
206    let mut options = request.options(&state.config.limits);
207    options.read_only |= auth.read_only;
208    let result = auto_commit(
209        state.config.database_path.clone(),
210        statement,
211        params,
212        options,
213        state.query_cancellation.clone(),
214        state.config.limits.max_result_rows,
215        state.config.limits.max_result_bytes,
216    )
217    .await
218    .map_err(|error| map_authorization_error(error, auth))?;
219    format.render(
220        QueryResponse {
221            result: Some(result),
222            transaction: None,
223        },
224        StatusCode::ACCEPTED,
225        state.config.limits.max_result_bytes,
226    )
227}
228
229async fn begin_transaction(
230    State(state): State<AppState>,
231    headers: HeaderMap,
232    body: Bytes,
233) -> Response {
234    let error_format = ResponseFormat::for_error(&headers);
235    handle_begin(state, &headers, &body)
236        .await
237        .unwrap_or_else(|error| error_format.render_error(error))
238}
239
240async fn handle_begin(
241    state: AppState,
242    headers: &HeaderMap,
243    body: &[u8],
244) -> std::result::Result<Response, HttpError> {
245    let _permit = admit(&state).await?;
246    let (request, format, auth) = parse_request(&state, headers, body)?;
247    let mut options = request.options(&state.config.limits);
248    options.read_only |= auth.read_only;
249    let info = state
250        .transactions
251        .begin(options, auth.principal)
252        .await
253        .map_err(|error| map_authorization_error(error, auth))?;
254    let (result, transaction) = match request.statement.as_deref() {
255        Some(statement) if !statement.is_empty() => {
256            let params = request.params()?;
257            let (result, info) = state
258                .transactions
259                .run(&info.id, auth.principal, statement.to_owned(), params)
260                .await
261                .map_err(|error| map_authorization_error(error, auth))?;
262            (Some(result), Some(info))
263        }
264        _ => (None, Some(info)),
265    };
266    let rollback_id = transaction.as_ref().map(|info| info.id.clone());
267    let response = format.render(
268        QueryResponse {
269            result,
270            transaction,
271        },
272        StatusCode::ACCEPTED,
273        state.config.limits.max_result_bytes,
274    );
275    if response.is_err() {
276        if let Some(id) = rollback_id {
277            let _ = state.transactions.rollback(&id, auth.principal).await;
278        }
279    }
280    response
281}
282
283async fn continue_transaction(
284    State(state): State<AppState>,
285    Path(tx_id): Path<String>,
286    headers: HeaderMap,
287    body: Bytes,
288) -> Response {
289    let error_format = ResponseFormat::for_error(&headers);
290    handle_continue(state, tx_id, &headers, &body)
291        .await
292        .unwrap_or_else(|error| error_format.render_error(error))
293}
294
295async fn handle_continue(
296    state: AppState,
297    tx_id: String,
298    headers: &HeaderMap,
299    body: &[u8],
300) -> std::result::Result<Response, HttpError> {
301    let _permit = admit(&state).await?;
302    let (request, format, auth) = parse_request(&state, headers, body)?;
303    let params = request.params()?;
304    let (result, transaction) = match request.statement {
305        Some(statement) => {
306            let (result, info) = state
307                .transactions
308                .run(&tx_id, auth.principal, statement, params)
309                .await
310                .map_err(|error| map_authorization_error(error, auth))?;
311            (Some(result), Some(info))
312        }
313        None => (
314            None,
315            Some(
316                state
317                    .transactions
318                    .keep_alive(&tx_id, auth.principal)
319                    .await?,
320            ),
321        ),
322    };
323    let rollback_id = transaction.as_ref().map(|info| info.id.clone());
324    let response = format.render(
325        QueryResponse {
326            result,
327            transaction,
328        },
329        StatusCode::ACCEPTED,
330        state.config.limits.max_result_bytes,
331    );
332    if response.is_err() {
333        if let Some(id) = rollback_id {
334            let _ = state.transactions.rollback(&id, auth.principal).await;
335        }
336    }
337    response
338}
339
340async fn commit_transaction(
341    State(state): State<AppState>,
342    Path(tx_id): Path<String>,
343    headers: HeaderMap,
344    body: Bytes,
345) -> Response {
346    let error_format = ResponseFormat::for_error(&headers);
347    handle_commit(state, tx_id, &headers, &body)
348        .await
349        .unwrap_or_else(|error| error_format.render_error(error))
350}
351
352async fn handle_commit(
353    state: AppState,
354    tx_id: String,
355    headers: &HeaderMap,
356    body: &[u8],
357) -> std::result::Result<Response, HttpError> {
358    let _permit = admit(&state).await?;
359    let (request, format, auth) = parse_request(&state, headers, body)?;
360    let params = request.params()?;
361    let query = request.statement.map(|statement| (statement, params));
362    let result = state
363        .transactions
364        .commit(&tx_id, auth.principal, query)
365        .await
366        .map_err(|error| map_authorization_error(error, auth))?;
367    format.render(
368        QueryResponse {
369            result,
370            transaction: None,
371        },
372        StatusCode::ACCEPTED,
373        state.config.limits.max_result_bytes,
374    )
375}
376
377async fn rollback_transaction(
378    State(state): State<AppState>,
379    Path(tx_id): Path<String>,
380    headers: HeaderMap,
381) -> Response {
382    let error_format = ResponseFormat::for_error(&headers);
383    async {
384        let _permit = admit(&state).await?;
385        let auth = authenticate(&state.config.auth, &headers)?;
386        let format = ResponseFormat::negotiate(&headers)?;
387        state.transactions.rollback(&tx_id, auth.principal).await?;
388        format.render(
389            QueryResponse {
390                result: None,
391                transaction: None,
392            },
393            StatusCode::OK,
394            state.config.limits.max_result_bytes,
395        )
396    }
397    .await
398    .unwrap_or_else(|error| error_format.render_error(error))
399}
400
401fn parse_request(
402    state: &AppState,
403    headers: &HeaderMap,
404    body: &[u8],
405) -> std::result::Result<(QueryRequest, ResponseFormat, AuthContext), HttpError> {
406    let auth = authenticate(&state.config.auth, headers)?;
407    let typed_parameters = ResponseFormat::validate_content_type(headers)?;
408    let format = ResponseFormat::negotiate(headers)?;
409    let mut request = if body.is_empty() {
410        QueryRequest::default()
411    } else {
412        serde_json::from_slice(body).map_err(|_| {
413            HttpError::new(
414                StatusCode::BAD_REQUEST,
415                "Neo.ClientError.Request.Invalid",
416                "Bad Request",
417            )
418        })?
419    };
420    request.typed_parameters = typed_parameters;
421    request.validate_extensions()?;
422    let _ = request.params()?;
423    Ok((request, format, auth))
424}
425
426async fn authenticate_request(
427    State(state): State<AppState>,
428    request: Request,
429    next: Next,
430) -> Response {
431    let error_format = ResponseFormat::for_error(request.headers());
432    match authenticate(&state.config.auth, request.headers()) {
433        Ok(_) => {
434            let response = next.run(request).await;
435            if response.status() == StatusCode::PAYLOAD_TOO_LARGE
436                && response
437                    .headers()
438                    .get(header::CONTENT_TYPE)
439                    .is_none_or(|value| {
440                        !value
441                            .to_str()
442                            .unwrap_or_default()
443                            .starts_with("application/json")
444                    })
445            {
446                error_format.render_error(HttpError::new(
447                    StatusCode::PAYLOAD_TOO_LARGE,
448                    "Neo.ClientError.Request.Invalid",
449                    "request body exceeds the configured limit",
450                ))
451            } else if response.status() == StatusCode::METHOD_NOT_ALLOWED {
452                error_format.render_error(HttpError::new(
453                    StatusCode::METHOD_NOT_ALLOWED,
454                    "Neo.ClientError.Request.Invalid",
455                    "Method Not Allowed",
456                ))
457            } else {
458                response
459            }
460        }
461        Err(error) => error_format.render_error(error),
462    }
463}
464
465async fn route_not_found(headers: HeaderMap) -> Response {
466    let error_format = ResponseFormat::for_error(&headers);
467    error_format.render_error(HttpError::new(
468        StatusCode::NOT_FOUND,
469        "Neo.ClientError.Database.DatabaseNotFound",
470        "The requested Query API database or endpoint was not found.",
471    ))
472}
473
474fn authenticate(
475    expected: &Option<QueryApiAuth>,
476    headers: &HeaderMap,
477) -> std::result::Result<AuthContext, HttpError> {
478    let Some(expected) = expected else {
479        return Ok(AuthContext::anonymous());
480    };
481    let mut values = headers.get_all(header::AUTHORIZATION).iter();
482    let Some(value) = values.next() else {
483        return Err(HttpError::unauthorized(
484            "No authentication header supplied.",
485        ));
486    };
487    if values.next().is_some() {
488        return Err(HttpError::new(
489            StatusCode::BAD_REQUEST,
490            "Neo.ClientError.Request.InvalidFormat",
491            "Multiple authentication headers supplied.",
492        ));
493    }
494    let value = value.to_str().map_err(|_| {
495        HttpError::new(
496            StatusCode::BAD_REQUEST,
497            "Neo.ClientError.Request.InvalidFormat",
498            "Invalid authentication header.",
499        )
500    })?;
501    let Some((scheme, credential)) = value.trim().split_once(' ') else {
502        return Err(HttpError::new(
503            StatusCode::BAD_REQUEST,
504            "Neo.ClientError.Request.InvalidFormat",
505            "Invalid authentication header.",
506        ));
507    };
508    if credential.is_empty() || credential.contains(' ') {
509        return Err(HttpError::new(
510            StatusCode::BAD_REQUEST,
511            "Neo.ClientError.Request.InvalidFormat",
512            "Invalid authentication header.",
513        ));
514    }
515    let authenticated = if scheme.eq_ignore_ascii_case("Bearer") {
516        expected.authenticate("", credential)
517    } else if scheme.eq_ignore_ascii_case("Basic") {
518        let decoded = BASE64_STANDARD.decode(credential).map_err(|_| {
519            HttpError::new(
520                StatusCode::BAD_REQUEST,
521                "Neo.ClientError.Request.InvalidFormat",
522                "Invalid authentication header.",
523            )
524        })?;
525        let decoded = std::str::from_utf8(&decoded).map_err(|_| {
526            HttpError::new(
527                StatusCode::BAD_REQUEST,
528                "Neo.ClientError.Request.InvalidFormat",
529                "Invalid authentication header.",
530            )
531        })?;
532        let (username, password) = decoded.split_once(':').ok_or_else(|| {
533            HttpError::new(
534                StatusCode::BAD_REQUEST,
535                "Neo.ClientError.Request.InvalidFormat",
536                "Invalid authentication header.",
537            )
538        })?;
539        expected.authenticate(username, password)
540    } else {
541        return Err(HttpError::new(
542            StatusCode::BAD_REQUEST,
543            "Neo.ClientError.Request.InvalidFormat",
544            "Invalid authentication header.",
545        ));
546    };
547    authenticated.ok_or_else(|| HttpError::unauthorized("Invalid credential."))
548}
549
550fn map_authorization_error(error: HttpError, auth: AuthContext) -> HttpError {
551    if auth.read_only && error.code == "Neo.ClientError.Statement.AccessMode" {
552        HttpError::new(
553            StatusCode::FORBIDDEN,
554            "Neo.ClientError.Security.Forbidden",
555            "Permission denied.",
556        )
557    } else {
558        error
559    }
560}
561
562async fn admit(state: &AppState) -> std::result::Result<OwnedSemaphorePermit, HttpError> {
563    state.requests.clone().try_acquire_owned().map_err(|_| {
564        HttpError::new(
565            StatusCode::SERVICE_UNAVAILABLE,
566            "Neo.TransientError.General.DatabaseUnavailable",
567            "the Query API request limit was reached",
568        )
569    })
570}
571
572#[cfg(test)]
573mod tests {
574    use std::io::Write;
575    use std::path::Path;
576    use std::sync::Arc;
577
578    use axum::http::HeaderValue;
579    use littlegraph_core::Neo4jStorage;
580    use rcgen::{CertificateParams, KeyPair};
581    use rustls::pki_types::ServerName;
582    use serde_json::json;
583    use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
584    use tokio_rustls::TlsConnector;
585
586    use super::*;
587    use crate::{QueryApiLimits, QueryApiServerConfig, QueryApiTlsConfig};
588
589    async fn start_server(
590        database: &Path,
591        auth: Option<QueryApiAuth>,
592    ) -> (
593        SocketAddr,
594        CancellationToken,
595        tokio::task::JoinHandle<Result<()>>,
596    ) {
597        Neo4jStorage::initialize_if_empty(database).unwrap();
598        let server = QueryApiServer::bind(QueryApiServerConfig {
599            listen_addr: "127.0.0.1:0".parse().unwrap(),
600            database_path: database.to_owned(),
601            auth,
602            tls: None,
603            limits: QueryApiLimits::default(),
604        })
605        .await
606        .unwrap();
607        let address = server.local_addr().unwrap();
608        let shutdown = CancellationToken::new();
609        let serve_shutdown = shutdown.clone();
610        let task = tokio::spawn(server.serve(serve_shutdown));
611        (address, shutdown, task)
612    }
613
614    fn auth(contents: &str) -> QueryApiAuth {
615        let mut file = tempfile::NamedTempFile::new().unwrap();
616        file.write_all(contents.as_bytes()).unwrap();
617        QueryApiAuth::from_file(file.path()).unwrap()
618    }
619
620    async fn request(
621        address: SocketAddr,
622        method: &str,
623        path: &str,
624        body: &str,
625        authorization: Option<&str>,
626    ) -> (u16, HeaderMap, serde_json::Value) {
627        let stream = tokio::net::TcpStream::connect(address).await.unwrap();
628        exchange(stream, address, method, path, body, authorization).await
629    }
630
631    async fn request_with_media_types(
632        address: SocketAddr,
633        method: &str,
634        path: &str,
635        body: &str,
636        authorization: Option<&str>,
637        content_type: &str,
638        accept: &str,
639    ) -> (u16, HeaderMap, serde_json::Value) {
640        let stream = tokio::net::TcpStream::connect(address).await.unwrap();
641        exchange_with_media_types(
642            stream,
643            address,
644            method,
645            path,
646            body,
647            authorization,
648            content_type,
649            accept,
650        )
651        .await
652    }
653
654    async fn exchange<S>(
655        stream: S,
656        address: SocketAddr,
657        method: &str,
658        path: &str,
659        body: &str,
660        authorization: Option<&str>,
661    ) -> (u16, HeaderMap, serde_json::Value)
662    where
663        S: AsyncRead + AsyncWrite + Unpin,
664    {
665        exchange_with_media_types(
666            stream,
667            address,
668            method,
669            path,
670            body,
671            authorization,
672            "application/json",
673            "application/json",
674        )
675        .await
676    }
677
678    #[allow(clippy::too_many_arguments)]
679    async fn exchange_with_media_types<S>(
680        mut stream: S,
681        address: SocketAddr,
682        method: &str,
683        path: &str,
684        body: &str,
685        authorization: Option<&str>,
686        content_type: &str,
687        accept: &str,
688    ) -> (u16, HeaderMap, serde_json::Value)
689    where
690        S: AsyncRead + AsyncWrite + Unpin,
691    {
692        let authorization = authorization
693            .map(|value| format!("Authorization: {value}\r\n"))
694            .unwrap_or_default();
695        let request = format!(
696            "{method} {path} HTTP/1.1\r\nHost: {address}\r\nContent-Type: {content_type}\r\nAccept: {accept}\r\n{authorization}Content-Length: {}\r\nConnection: close\r\n\r\n{body}",
697            body.len()
698        );
699        stream.write_all(request.as_bytes()).await.unwrap();
700        let mut response = Vec::new();
701        stream.read_to_end(&mut response).await.unwrap();
702        let separator = response
703            .windows(4)
704            .position(|window| window == b"\r\n\r\n")
705            .unwrap();
706        let head = std::str::from_utf8(&response[..separator]).unwrap();
707        let status = head
708            .lines()
709            .next()
710            .unwrap()
711            .split_whitespace()
712            .nth(1)
713            .unwrap()
714            .parse()
715            .unwrap();
716        let mut headers = HeaderMap::new();
717        for line in head.lines().skip(1) {
718            let (name, value) = line.split_once(':').unwrap();
719            headers.insert(
720                axum::http::HeaderName::from_bytes(name.as_bytes()).unwrap(),
721                HeaderValue::from_str(value.trim()).unwrap(),
722            );
723        }
724        let body = &response[separator + 4..];
725        let json = if body.is_empty() {
726            json!({})
727        } else {
728            serde_json::from_slice(body).unwrap()
729        };
730        (status, headers, json)
731    }
732
733    #[tokio::test]
734    async fn executes_auto_commit_and_explicit_transactions() {
735        let directory = tempfile::tempdir().unwrap();
736        let database = directory.path().join("neo4j");
737        let (address, shutdown, task) = start_server(&database, None).await;
738
739        let (status, _, body) =
740            request(address, "POST", ROOT, r#"{"statement":"RETURN 1"}"#, None).await;
741        assert_eq!(status, 202, "unexpected response: {body}");
742        assert_eq!(body["data"]["values"], json!([[1]]));
743
744        let (status, _, body) = request(
745            address,
746            "POST",
747            &format!("{ROOT}/tx"),
748            r#"{"statement":"CREATE (:QueryApiNode)"}"#,
749            None,
750        )
751        .await;
752        assert_eq!(status, 202);
753        let tx_id = body["transaction"]["id"].as_str().unwrap();
754        assert_eq!(tx_id.len(), 6);
755        let (status, _, body) = request(
756            address,
757            "POST",
758            &format!("{ROOT}/tx/{tx_id}/commit"),
759            "{}",
760            None,
761        )
762        .await;
763        assert_eq!(status, 202);
764        assert_eq!(body, json!({}));
765
766        let (status, _, body) = request(
767            address,
768            "POST",
769            ROOT,
770            r#"{"statement":"MATCH (n:QueryApiNode) RETURN n"}"#,
771            None,
772        )
773        .await;
774        assert_eq!(status, 202, "unexpected response: {body}");
775        assert_eq!(body["data"]["values"].as_array().unwrap().len(), 1);
776
777        let (_, _, body) = request(
778            address,
779            "POST",
780            &format!("{ROOT}/tx"),
781            r#"{"statement":"CREATE (:RolledBackNode)"}"#,
782            None,
783        )
784        .await;
785        let tx_id = body["transaction"]["id"].as_str().unwrap();
786        let (status, _, body) =
787            request(address, "DELETE", &format!("{ROOT}/tx/{tx_id}"), "", None).await;
788        assert_eq!(status, 200);
789        assert_eq!(body, json!({}));
790        let (status, _, body) = request(
791            address,
792            "POST",
793            &format!("{ROOT}/tx/{tx_id}/commit"),
794            "{}",
795            None,
796        )
797        .await;
798        assert_eq!(status, 404);
799        assert_eq!(body["errors"][0]["code"], "Neo.ClientError.Request.Invalid");
800        assert_eq!(
801            body["errors"][0]["message"],
802            format!(
803                "Transaction with Id: \"{tx_id}\" was not found. It may have timed out and \
804                 therefore rolled back or the routing header 'neo4j-cluster-affinity' was not \
805                 provided."
806            )
807        );
808
809        let (status, _, body) = request(
810            address,
811            "POST",
812            "/db/other/query/v2",
813            r#"{"statement":"RETURN 1"}"#,
814            None,
815        )
816        .await;
817        assert_eq!(status, 404);
818        assert_eq!(
819            body["errors"][0]["code"],
820            "Neo.ClientError.Database.DatabaseNotFound"
821        );
822
823        shutdown.cancel();
824        task.await.unwrap().unwrap();
825    }
826
827    #[tokio::test]
828    async fn enforces_bearer_authentication_before_query_handling() {
829        let directory = tempfile::tempdir().unwrap();
830        let database = directory.path().join("neo4j");
831        let auth = auth("rw::test-secret\nro:reader:reader-secret\nrw:writer:writer-secret\n");
832        let (address, shutdown, task) = start_server(&database, Some(auth)).await;
833
834        let (status, headers, body) = request(address, "POST", ROOT, "not-json", None).await;
835        assert_eq!(status, 401);
836        assert_eq!(
837            headers[header::WWW_AUTHENTICATE],
838            "Basic realm=\"Neo4j\", Bearer realm=\"Neo4j\""
839        );
840        assert_eq!(
841            body["errors"][0]["code"],
842            "Neo.ClientError.Security.Unauthorized"
843        );
844
845        let (status, _, _) = request(
846            address,
847            "POST",
848            ROOT,
849            r#"{"statement":"RETURN 1"}"#,
850            Some("Bearer wrong"),
851        )
852        .await;
853        assert_eq!(status, 401);
854
855        let (status, _, body) = request(
856            address,
857            "POST",
858            ROOT,
859            r#"{"statement":"RETURN 1"}"#,
860            Some("Bearer test-secret"),
861        )
862        .await;
863        assert_eq!(status, 202);
864        assert_eq!(body["data"]["values"], json!([[1]]));
865
866        let (status, _, body) = request(
867            address,
868            "POST",
869            ROOT,
870            r#"{"statement":"RETURN 2"}"#,
871            Some("bearer test-secret"),
872        )
873        .await;
874        assert_eq!(status, 202);
875        assert_eq!(body["data"]["values"], json!([[2]]));
876
877        let reader = format!("Basic {}", BASE64_STANDARD.encode("reader:reader-secret"));
878        let writer = format!("Basic {}", BASE64_STANDARD.encode("writer:writer-secret"));
879        let (status, _, body) = request(
880            address,
881            "POST",
882            ROOT,
883            r#"{"statement":"RETURN 3"}"#,
884            Some(&reader),
885        )
886        .await;
887        assert_eq!(status, 202);
888        assert_eq!(body["data"]["values"], json!([[3]]));
889
890        let (status, _, body) = request(
891            address,
892            "POST",
893            ROOT,
894            r#"{"statement":"CREATE (:DeniedReader)"}"#,
895            Some(&reader),
896        )
897        .await;
898        assert_eq!(status, 403);
899        assert_eq!(
900            body["errors"][0]["code"],
901            "Neo.ClientError.Security.Forbidden"
902        );
903
904        let (status, _, body) = request(
905            address,
906            "POST",
907            &format!("{ROOT}/tx"),
908            r#"{"statement":"RETURN 4"}"#,
909            Some(&reader),
910        )
911        .await;
912        assert_eq!(status, 202, "unexpected response: {body}");
913        let tx_id = body["transaction"]["id"].as_str().unwrap();
914
915        let (status, _, _) = request(
916            address,
917            "POST",
918            &format!("{ROOT}/tx/{tx_id}"),
919            r#"{"statement":"RETURN 5"}"#,
920            Some(&writer),
921        )
922        .await;
923        assert_eq!(status, 404);
924
925        let (status, _, body) = request(
926            address,
927            "POST",
928            &format!("{ROOT}/tx/{tx_id}"),
929            r#"{"statement":"CREATE (:DeniedExplicitReader)"}"#,
930            Some(&reader),
931        )
932        .await;
933        assert_eq!(status, 403);
934        assert_eq!(
935            body["errors"][0]["code"],
936            "Neo.ClientError.Security.Forbidden"
937        );
938
939        let (status, _, body) = request(
940            address,
941            "POST",
942            ROOT,
943            r#"{"statement":"CREATE (:AllowedWriter)"}"#,
944            Some(&writer),
945        )
946        .await;
947        assert_eq!(status, 202, "unexpected response: {body}");
948
949        shutdown.cancel();
950        task.await.unwrap().unwrap();
951    }
952
953    #[tokio::test]
954    async fn enforces_case_insensitive_read_access_mode() {
955        let directory = tempfile::tempdir().unwrap();
956        let database = directory.path().join("neo4j");
957        let (address, shutdown, task) = start_server(&database, None).await;
958
959        let (status, _, body) = request(
960            address,
961            "POST",
962            ROOT,
963            r#"{"statement":"RETURN 1","accessMode":"read"}"#,
964            None,
965        )
966        .await;
967        assert_eq!(status, 202, "unexpected response: {body}");
968
969        let (status, _, body) = request(
970            address,
971            "POST",
972            ROOT,
973            r#"{"statement":"CREATE (:DeniedAutoCommit)","accessMode":"Read"}"#,
974            None,
975        )
976        .await;
977        assert_eq!(status, 400);
978        assert_eq!(
979            body["errors"][0]["code"],
980            "Neo.ClientError.Statement.AccessMode"
981        );
982
983        let (status, _, body) = request(
984            address,
985            "POST",
986            &format!("{ROOT}/tx"),
987            r#"{"accessMode":"READ"}"#,
988            None,
989        )
990        .await;
991        assert_eq!(status, 202);
992        let tx_id = body["transaction"]["id"].as_str().unwrap();
993        let (status, _, body) = request(
994            address,
995            "POST",
996            &format!("{ROOT}/tx/{tx_id}"),
997            r#"{"statement":"CREATE (:DeniedExplicit)"}"#,
998            None,
999        )
1000        .await;
1001        assert_eq!(status, 400);
1002        assert_eq!(
1003            body["errors"][0]["code"],
1004            "Neo.ClientError.Statement.AccessMode"
1005        );
1006
1007        let (status, _, _) = request(
1008            address,
1009            "POST",
1010            &format!("{ROOT}/tx/{tx_id}/commit"),
1011            "{}",
1012            None,
1013        )
1014        .await;
1015        assert_eq!(status, 404);
1016
1017        shutdown.cancel();
1018        task.await.unwrap().unwrap();
1019    }
1020
1021    #[tokio::test]
1022    async fn renders_request_and_query_errors_as_json_lines() {
1023        let directory = tempfile::tempdir().unwrap();
1024        let database = directory.path().join("neo4j");
1025        let (address, shutdown, task) = start_server(&database, None).await;
1026
1027        let (status, headers, body) = request_with_media_types(
1028            address,
1029            "POST",
1030            ROOT,
1031            r#"{"statement":"THIS IS NOT CYPHER"}"#,
1032            None,
1033            "application/json",
1034            "application/jsonl",
1035        )
1036        .await;
1037        assert_eq!(status, 400);
1038        assert_eq!(headers[header::CONTENT_TYPE], "application/jsonl");
1039        assert_eq!(body["$event"], "Error");
1040        assert_eq!(
1041            body["_body"]["errors"][0]["code"],
1042            "Neo.ClientError.Statement.SyntaxError"
1043        );
1044
1045        let (status, headers, body) = request_with_media_types(
1046            address,
1047            "POST",
1048            ROOT,
1049            "",
1050            None,
1051            "application/json",
1052            "application/jsonl",
1053        )
1054        .await;
1055        assert_eq!(status, 400);
1056        assert_eq!(headers[header::CONTENT_TYPE], "application/jsonl");
1057        assert_eq!(
1058            body["_body"]["errors"][0],
1059            json!({
1060                "code": "Neo.ClientError.Request.Invalid",
1061                "message": "statement cannot be null or empty"
1062            })
1063        );
1064
1065        let (status, headers, body) = request_with_media_types(
1066            address,
1067            "POST",
1068            ROOT,
1069            "not-json",
1070            None,
1071            "application/json",
1072            "application/jsonl",
1073        )
1074        .await;
1075        assert_eq!(status, 400);
1076        assert_eq!(headers[header::CONTENT_TYPE], "application/jsonl");
1077        assert_eq!(
1078            body["_body"]["errors"][0],
1079            json!({
1080                "code": "Neo.ClientError.Request.Invalid",
1081                "message": "Bad Request"
1082            })
1083        );
1084
1085        let (status, headers, body) = request_with_media_types(
1086            address,
1087            "POST",
1088            ROOT,
1089            "not-json",
1090            None,
1091            "text/csv",
1092            "application/jsonl",
1093        )
1094        .await;
1095        assert_eq!(status, 415);
1096        assert_eq!(headers[header::CONTENT_TYPE], "application/jsonl");
1097        assert_eq!(body["$event"], "Error");
1098        assert_eq!(
1099            body["_body"]["errors"][0]["code"],
1100            "Neo.ClientError.Request.Invalid"
1101        );
1102
1103        let (status, headers, body) = request_with_media_types(
1104            address,
1105            "GET",
1106            ROOT,
1107            "",
1108            None,
1109            "application/json",
1110            "application/jsonl",
1111        )
1112        .await;
1113        assert_eq!(status, 405);
1114        assert_eq!(headers[header::CONTENT_TYPE], "application/jsonl");
1115        assert_eq!(
1116            body["_body"]["errors"][0],
1117            json!({
1118                "code": "Neo.ClientError.Request.Invalid",
1119                "message": "Method Not Allowed"
1120            })
1121        );
1122
1123        shutdown.cancel();
1124        task.await.unwrap().unwrap();
1125    }
1126
1127    #[tokio::test]
1128    async fn enforces_neo4j_max_execution_time_integer_semantics() {
1129        let directory = tempfile::tempdir().unwrap();
1130        let database = directory.path().join("neo4j");
1131        let (address, shutdown, task) = start_server(&database, None).await;
1132
1133        let (status, _, body) = request(
1134            address,
1135            "POST",
1136            ROOT,
1137            r#"{"statement":"RETURN 1","maxExecutionTime":-1}"#,
1138            None,
1139        )
1140        .await;
1141        assert_eq!(status, 202, "unexpected response: {body}");
1142
1143        let (status, _, body) = request(
1144            address,
1145            "POST",
1146            ROOT,
1147            r#"{"statement":"RETURN 1","maxExecutionTime":2147483648}"#,
1148            None,
1149        )
1150        .await;
1151        assert_eq!(status, 400);
1152        assert_eq!(body["errors"][0]["code"], "Neo.ClientError.Request.Invalid");
1153        assert_eq!(body["errors"][0]["message"], "Bad Request");
1154
1155        shutdown.cancel();
1156        task.await.unwrap().unwrap();
1157    }
1158
1159    #[tokio::test]
1160    async fn renders_authentication_errors_as_json_lines() {
1161        let directory = tempfile::tempdir().unwrap();
1162        let database = directory.path().join("neo4j");
1163        let auth = auth("rw::test-secret\n");
1164        let (address, shutdown, task) = start_server(&database, Some(auth)).await;
1165
1166        for authorization in [None, Some("Bearer wrong")] {
1167            let (status, headers, body) = request_with_media_types(
1168                address,
1169                "POST",
1170                ROOT,
1171                r#"{"statement":"RETURN 1"}"#,
1172                authorization,
1173                "application/json",
1174                "application/vnd.neo4j.query.v1.1+jsonl",
1175            )
1176            .await;
1177            assert_eq!(status, 401);
1178            assert_eq!(
1179                headers[header::CONTENT_TYPE],
1180                "application/vnd.neo4j.query.v1.1+jsonl"
1181            );
1182            assert_eq!(
1183                headers[header::WWW_AUTHENTICATE],
1184                "Basic realm=\"Neo4j\", Bearer realm=\"Neo4j\""
1185            );
1186            assert_eq!(body["$event"], "Error");
1187            assert_eq!(
1188                body["_body"]["errors"][0]["code"],
1189                "Neo.ClientError.Security.Unauthorized"
1190            );
1191        }
1192
1193        shutdown.cancel();
1194        task.await.unwrap().unwrap();
1195    }
1196
1197    #[tokio::test]
1198    async fn serves_query_api_over_tls_with_the_combined_pem_bundle() {
1199        let directory = tempfile::tempdir().unwrap();
1200        let database = directory.path().join("neo4j");
1201        Neo4jStorage::initialize_if_empty(&database).unwrap();
1202        let key = KeyPair::generate().unwrap();
1203        let certificate = CertificateParams::new(vec!["localhost".into()])
1204            .unwrap()
1205            .self_signed(&key)
1206            .unwrap();
1207        let pem_path = directory.path().join("server.pem");
1208        let mut pem_file = std::fs::File::create(&pem_path).unwrap();
1209        write!(pem_file, "{}{}", certificate.pem(), key.serialize_pem()).unwrap();
1210
1211        let limits = QueryApiLimits {
1212            tls_handshake_timeout: Duration::from_millis(100),
1213            ..QueryApiLimits::default()
1214        };
1215        let server = QueryApiServer::bind(QueryApiServerConfig {
1216            listen_addr: "127.0.0.1:0".parse().unwrap(),
1217            database_path: database,
1218            auth: None,
1219            tls: Some(QueryApiTlsConfig {
1220                certificate_file: pem_path,
1221                ca_file: None,
1222            }),
1223            limits,
1224        })
1225        .await
1226        .unwrap();
1227        let address = server.local_addr().unwrap();
1228        let shutdown = CancellationToken::new();
1229        let serve_shutdown = shutdown.clone();
1230        let task = tokio::spawn(server.serve(serve_shutdown));
1231
1232        let mut stalled = tokio::net::TcpStream::connect(address).await.unwrap();
1233        let mut byte = [0];
1234        let closed = tokio::time::timeout(Duration::from_secs(1), stalled.read(&mut byte))
1235            .await
1236            .expect("stalled TLS handshake was not closed");
1237        assert!(
1238            matches!(closed, Ok(0) | Err(_)),
1239            "stalled TLS connection unexpectedly produced application data"
1240        );
1241
1242        let mut roots = rustls::RootCertStore::empty();
1243        roots.add(certificate.der().clone()).unwrap();
1244        let client = rustls::ClientConfig::builder()
1245            .with_root_certificates(roots)
1246            .with_no_client_auth();
1247        let tcp = tokio::net::TcpStream::connect(address).await.unwrap();
1248        let tls = TlsConnector::from(Arc::new(client))
1249            .connect(ServerName::try_from("localhost").unwrap(), tcp)
1250            .await
1251            .unwrap();
1252        let (status, _, body) = exchange(
1253            tls,
1254            address,
1255            "POST",
1256            ROOT,
1257            r#"{"statement":"RETURN 1"}"#,
1258            None,
1259        )
1260        .await;
1261        assert_eq!(status, 202);
1262        assert_eq!(body["data"]["values"], json!([[1]]));
1263
1264        shutdown.cancel();
1265        task.await.unwrap().unwrap();
1266    }
1267}