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
35pub struct QueryApiServer {
37 listener: std::net::TcpListener,
38 state: AppState,
39 tls: Option<RustlsConfig>,
40}
41
42impl QueryApiServer {
43 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 pub fn local_addr(&self) -> Result<SocketAddr> {
115 Ok(self.listener.local_addr()?)
116 }
117
118 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}