Skip to main content

shard_telemetry/
native_server.rs

1use std::future::Future;
2use std::io;
3use std::sync::Arc;
4
5use tokio::io::{AsyncReadExt, AsyncWriteExt};
6use tokio::net::{TcpListener, TcpStream};
7use tokio::sync::{OwnedSemaphorePermit, Semaphore, mpsc};
8
9use crate::loki_api::LokiApiError;
10use crate::{
11    DurableTelemetryStore, MAX_NATIVE_FRAME_BYTES, NATIVE_FRAME_HEADER_BYTES, NativeCapabilities,
12    NativeFrame, NativeFrameHeader, NativeOpcode, NativeStatus, NativeTelemetryBatch,
13    ProductionRuntime, ServiceState, decode_native_metric_query, decode_native_query,
14    decode_native_trace_query, encode_native_capabilities, encode_native_log_query_result,
15    encode_native_metric_query_result, encode_native_trace_query_result, is_native_telemetry_batch,
16};
17
18/// Product-owned admission check evaluated for every native append and query.
19///
20/// HA distributions use this to fence direct native traffic on followers while
21/// allowing an existing connection to follow leadership changes safely.
22pub trait NativeRequestGate: Send + Sync + std::fmt::Debug + 'static {
23    /// Returns `Ok` only when this process may execute the request.
24    fn check(&self) -> Result<(), String>;
25
26    /// Returns `Ok` only when this process can execute a complete native
27    /// query. The default keeps coordinator-only gates compatible. HA
28    /// products override this when a node hosts only a subset of signal
29    /// partitions, preventing a local query from being mistaken for a
30    /// cluster-wide result.
31    fn check_query(&self) -> Result<(), String> {
32        self.check()
33    }
34
35    /// Applies product-specific capability constraints before `Describe`
36    /// responds. A partitioned HA node can therefore advertise append support
37    /// while explicitly withholding query support until it is a complete
38    /// query replica, rather than returning silently partial data.
39    fn capabilities(&self, capabilities: NativeCapabilities) -> NativeCapabilities {
40        capabilities
41    }
42
43    /// Returns `Ok` only when this process may append every routed partition.
44    ///
45    /// The default preserves coordinator-only gates. HA products override this
46    /// method to fence each signal partition after the complete STB1 request is
47    /// decoded and before any partition append starts.
48    fn check_partitions(&self, _partitions: &[crate::NativePartitionAppend]) -> Result<(), String> {
49        self.check()
50    }
51}
52
53/// Runtime limits for the native TCP listener.
54#[derive(Debug, Clone)]
55pub struct NativeServerConfig {
56    /// Largest accepted payload, bounded by [`MAX_NATIVE_FRAME_BYTES`].
57    pub max_frame_bytes: usize,
58    /// Maximum requests executing concurrently on one connection.
59    pub max_in_flight_per_connection: usize,
60    /// Maximum response bytes queued or being written for one connection.
61    pub max_outbound_bytes_per_connection: usize,
62    /// Maximum response bytes reserved across every native connection.
63    pub max_outbound_bytes_total: usize,
64    /// Maximum request payload bytes buffered across every native connection.
65    ///
66    /// A reservation is acquired before allocating a frame body and retained
67    /// until request dispatch completes. This prevents many valid, large
68    /// frames from turning into unbounded process memory use.
69    pub max_inbound_bytes_total: usize,
70    /// Deadline for one complete native response write.
71    pub write_timeout: std::time::Duration,
72    /// Wait for exact-query visibility before acknowledging native appends.
73    ///
74    /// When false, acknowledgement means the authoritative checksummed
75    /// STEL envelope is durable and indexing continues under bounded
76    /// shard-stream backpressure.
77    pub wait_for_index: bool,
78    /// Shared authentication, tenant, lifecycle, and admission controls.
79    ///
80    /// `None` is intended only for tests and explicit development mode.
81    pub production: Option<Arc<ProductionRuntime>>,
82    /// Optional product-owned fencing check for append and query operations.
83    pub request_gate: Option<Arc<dyn NativeRequestGate>>,
84    /// Explicitly permits raw native TCP from non-loopback peers in production.
85    ///
86    /// Keep this disabled unless a local TLS/service-mesh ingress is the
87    /// actual encryption boundary for the accepted connection.
88    pub allow_insecure_remote: bool,
89}
90
91impl Default for NativeServerConfig {
92    fn default() -> Self {
93        Self {
94            max_frame_bytes: MAX_NATIVE_FRAME_BYTES,
95            max_in_flight_per_connection: 64,
96            max_outbound_bytes_per_connection: 8 * 1024 * 1024,
97            max_outbound_bytes_total: 64 * 1024 * 1024,
98            max_inbound_bytes_total: MAX_NATIVE_FRAME_BYTES,
99            write_timeout: std::time::Duration::from_secs(15),
100            wait_for_index: true,
101            production: None,
102            request_gate: None,
103            allow_insecure_remote: false,
104        }
105    }
106}
107
108impl NativeServerConfig {
109    /// Validates listener memory, concurrency, and response-write bounds.
110    ///
111    /// Product constructors call this during preflight so a deployment cannot
112    /// report a healthy configuration and then fail while its listener starts.
113    pub fn validate(self) -> io::Result<Self> {
114        if self.max_frame_bytes == 0 || self.max_frame_bytes > MAX_NATIVE_FRAME_BYTES {
115            return Err(io::Error::new(
116                io::ErrorKind::InvalidInput,
117                format!("native max frame bytes must be in 1..={MAX_NATIVE_FRAME_BYTES}"),
118            ));
119        }
120        if self.max_in_flight_per_connection == 0 {
121            return Err(io::Error::new(
122                io::ErrorKind::InvalidInput,
123                "native max in-flight requests must be nonzero",
124            ));
125        }
126        if self.max_outbound_bytes_per_connection == 0
127            || self.max_outbound_bytes_per_connection > u32::MAX as usize
128        {
129            return Err(io::Error::new(
130                io::ErrorKind::InvalidInput,
131                "native per-connection outbound bytes must be in 1..=u32::MAX",
132            ));
133        }
134        if self.max_outbound_bytes_total < self.max_outbound_bytes_per_connection
135            || self.max_outbound_bytes_total > u32::MAX as usize
136        {
137            return Err(io::Error::new(
138                io::ErrorKind::InvalidInput,
139                "native total outbound bytes must be at least one connection and fit u32",
140            ));
141        }
142        if self.max_inbound_bytes_total < self.max_frame_bytes
143            || self.max_inbound_bytes_total > u32::MAX as usize
144        {
145            return Err(io::Error::new(
146                io::ErrorKind::InvalidInput,
147                "native total inbound bytes must cover one frame and fit u32",
148            ));
149        }
150        if self.write_timeout.is_zero() {
151            return Err(io::Error::new(
152                io::ErrorKind::InvalidInput,
153                "native write timeout must be nonzero",
154            ));
155        }
156        Ok(self)
157    }
158}
159
160/// A response whose byte reservations remain held until the writer finishes
161/// the socket write. This makes both queued and actively blocked responses
162/// count against the same limits.
163struct QueuedNativeResponse {
164    frame: NativeFrame,
165    _connection_bytes: OwnedSemaphorePermit,
166    _global_bytes: OwnedSemaphorePermit,
167}
168
169async fn enqueue_response(
170    sender: &mpsc::Sender<QueuedNativeResponse>,
171    response: NativeFrame,
172    connection_budget: Arc<Semaphore>,
173    global_budget: Arc<Semaphore>,
174    reserved_global: Option<OwnedSemaphorePermit>,
175    maximum_connection_bytes: usize,
176) -> io::Result<()> {
177    let response = bounded_response(response, maximum_connection_bytes);
178    let bytes = response
179        .payload
180        .len()
181        .saturating_add(NATIVE_FRAME_HEADER_BYTES);
182    let bytes = u32::try_from(bytes).map_err(|_| {
183        io::Error::new(
184            io::ErrorKind::InvalidData,
185            "native response exceeds outbound byte budget",
186        )
187    })?;
188    let connection_bytes = connection_budget
189        .acquire_many_owned(bytes)
190        .await
191        .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "native server stopped"))?;
192    let global_bytes = match reserved_global {
193        Some(permit) => permit,
194        None => global_budget
195            .acquire_many_owned(bytes)
196            .await
197            .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "native server stopped"))?,
198    };
199    sender
200        .send(QueuedNativeResponse {
201            frame: response,
202            _connection_bytes: connection_bytes,
203            _global_bytes: global_bytes,
204        })
205        .await
206        .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "native writer stopped"))
207}
208
209fn bounded_response(response: NativeFrame, maximum_connection_bytes: usize) -> NativeFrame {
210    if response
211        .payload
212        .len()
213        .saturating_add(NATIVE_FRAME_HEADER_BYTES)
214        <= maximum_connection_bytes
215    {
216        return response;
217    }
218    error_frame(
219        response.header,
220        NativeStatus::TooManyRequests,
221        "native response exceeds the configured outbound byte budget",
222    )
223}
224
225/// Serves multiplexed native connections until `shutdown` resolves.
226///
227/// Responses may complete out of order and are correlated by the request ID
228/// copied from each request frame.
229pub async fn serve_native<F>(
230    listener: TcpListener,
231    store: Arc<DurableTelemetryStore>,
232    config: NativeServerConfig,
233    shutdown: F,
234) -> io::Result<()>
235where
236    F: Future<Output = ()>,
237{
238    let config = config.validate()?;
239    let outbound_budget = Arc::new(Semaphore::new(config.max_outbound_bytes_total));
240    let inbound_budget = Arc::new(Semaphore::new(config.max_inbound_bytes_total));
241    tokio::pin!(shutdown);
242    loop {
243        tokio::select! {
244            biased;
245            () = &mut shutdown => return Ok(()),
246            accepted = listener.accept() => {
247                let (socket, peer) = accepted?;
248                if config.production.is_some()
249                    && !config.allow_insecure_remote
250                    && !peer.ip().is_loopback()
251                {
252                    continue;
253                }
254                socket.set_nodelay(true)?;
255                let store = Arc::clone(&store);
256                let config = config.clone();
257                let outbound_budget = Arc::clone(&outbound_budget);
258                let inbound_budget = Arc::clone(&inbound_budget);
259                let connection_permit = match &config.production {
260                    Some(runtime) => match runtime.try_native_connection() {
261                        Some(permit) => Some(permit),
262                        None => continue,
263                    },
264                    None => None,
265                };
266                tokio::spawn(async move {
267                    let _connection_permit = connection_permit;
268                    if let Err(error) = serve_connection(
269                        socket,
270                        store,
271                        config,
272                        outbound_budget,
273                        inbound_budget,
274                    ).await
275                        && error.kind() != io::ErrorKind::UnexpectedEof
276                        && error.kind() != io::ErrorKind::ConnectionReset
277                    {
278                        eprintln!("native ShardTelemetry connection failed: {error}");
279                    }
280                });
281            }
282        }
283    }
284}
285
286async fn serve_connection(
287    socket: TcpStream,
288    store: Arc<DurableTelemetryStore>,
289    config: NativeServerConfig,
290    outbound_budget: Arc<Semaphore>,
291    inbound_budget: Arc<Semaphore>,
292) -> io::Result<()> {
293    let (mut reader, mut writer) = socket.into_split();
294    let (responses, mut response_receiver) =
295        mpsc::channel::<QueuedNativeResponse>(config.max_in_flight_per_connection);
296    let write_timeout = config.write_timeout;
297    let writer_task = tokio::spawn(async move {
298        while let Some(response) = response_receiver.recv().await {
299            let write = async {
300                writer.write_all(&response.frame.header.encode()).await?;
301                writer.write_all(&response.frame.payload).await
302            };
303            tokio::time::timeout(write_timeout, write)
304                .await
305                .map_err(|_| {
306                    io::Error::new(io::ErrorKind::TimedOut, "native response write timed out")
307                })??;
308        }
309        writer.shutdown().await
310    });
311    let permits = Arc::new(Semaphore::new(config.max_in_flight_per_connection));
312    let connection_outbound = Arc::new(Semaphore::new(config.max_outbound_bytes_per_connection));
313    let mut authenticated = config.production.is_none();
314    let mut shutdown = config
315        .production
316        .as_ref()
317        .map(|runtime| runtime.lifecycle().subscribe_shutdown());
318    let authentication_deadline = config
319        .production
320        .as_ref()
321        .map(|runtime| tokio::time::Instant::now() + runtime.native_auth_timeout());
322
323    loop {
324        let mut encoded_header = [0; NATIVE_FRAME_HEADER_BYTES];
325        if shutdown.as_ref().is_some_and(|shutdown| *shutdown.borrow()) {
326            break;
327        }
328        let read = reader.read_exact(&mut encoded_header);
329        let read_result = match (shutdown.as_mut(), authenticated) {
330            (Some(shutdown), false) => tokio::select! {
331                biased;
332                _ = shutdown.changed() => break,
333                _ = tokio::time::sleep_until(authentication_deadline.expect("production deadline")) => break,
334                result = read => result,
335            },
336            (Some(shutdown), true) => tokio::select! {
337                biased;
338                _ = shutdown.changed() => break,
339                result = read => result,
340            },
341            (None, _) => read.await,
342        };
343        match read_result {
344            Ok(_) => {}
345            Err(error) if error.kind() == io::ErrorKind::UnexpectedEof => break,
346            Err(error) => return Err(error),
347        }
348        let header = NativeFrameHeader::decode(&encoded_header).map_err(invalid_data)?;
349        if header.payload_len as usize > config.max_frame_bytes {
350            return Err(io::Error::new(
351                io::ErrorKind::InvalidData,
352                "native frame exceeds the configured connection limit",
353            ));
354        }
355        let inbound_permit = if header.payload_len == 0 {
356            None
357        } else {
358            Some(
359                Arc::clone(&inbound_budget)
360                    .try_acquire_many_owned(header.payload_len)
361                    .map_err(|_| {
362                        io::Error::new(
363                            io::ErrorKind::WouldBlock,
364                            "native inbound byte budget is exhausted",
365                        )
366                    })?,
367            )
368        };
369        let mut payload = vec![0; header.payload_len as usize];
370        if !authenticated {
371            match shutdown.as_mut() {
372                Some(shutdown) => tokio::select! {
373                    biased;
374                    _ = shutdown.changed() => break,
375                    _ = tokio::time::sleep_until(authentication_deadline.expect("production deadline")) => break,
376                    result = reader.read_exact(&mut payload) => { result?; }
377                },
378                None => reader.read_exact(&mut payload).await.map(|_| ())?,
379            }
380        } else {
381            reader.read_exact(&mut payload).await?;
382        }
383        header.verify_payload(&payload).map_err(invalid_data)?;
384        if !authenticated {
385            let response = authenticate_frame(header, &payload, &config);
386            authenticated = response.header.status == NativeStatus::Ok;
387            enqueue_response(
388                &responses,
389                response,
390                Arc::clone(&connection_outbound),
391                Arc::clone(&outbound_budget),
392                None,
393                config.max_outbound_bytes_per_connection,
394            )
395            .await?;
396            if !authenticated {
397                break;
398            }
399            continue;
400        }
401        let permit = Arc::clone(&permits)
402            .acquire_owned()
403            .await
404            .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "native server stopped"))?;
405        let responses = responses.clone();
406        let store = Arc::clone(&store);
407        let request_config = config.clone();
408        let connection_outbound = Arc::clone(&connection_outbound);
409        let outbound_budget = Arc::clone(&outbound_budget);
410        tokio::spawn(async move {
411            let _inbound_permit = inbound_permit;
412            // Reserve a whole per-connection response window before executing
413            // a query. This bounds work whose exact encoded result size is not
414            // known until after stripe execution completes.
415            let query_outbound = if matches!(
416                header.opcode,
417                NativeOpcode::Query | NativeOpcode::QueryMetrics | NativeOpcode::QueryTraces
418            ) {
419                match outbound_budget
420                    .clone()
421                    .acquire_many_owned(request_config.max_outbound_bytes_per_connection as u32)
422                    .await
423                {
424                    Ok(permit) => Some(permit),
425                    Err(_) => return,
426                }
427            } else {
428                None
429            };
430            let response = if header.is_response || header.status != NativeStatus::Ok {
431                error_frame(
432                    header,
433                    NativeStatus::BadRequest,
434                    "clients must send request frames with status OK",
435                )
436            } else {
437                dispatch(header, payload, store, &request_config).await
438            };
439            let _ = enqueue_response(
440                &responses,
441                response,
442                connection_outbound,
443                outbound_budget,
444                query_outbound,
445                request_config.max_outbound_bytes_per_connection,
446            )
447            .await;
448            drop(permit);
449        });
450    }
451
452    drop(responses);
453    writer_task
454        .await
455        .map_err(|error| io::Error::other(format!("native writer task failed: {error}")))?
456}
457
458fn authenticate_frame(
459    header: NativeFrameHeader,
460    payload: &[u8],
461    config: &NativeServerConfig,
462) -> NativeFrame {
463    if header.is_response || header.status != NativeStatus::Ok {
464        return error_frame(
465            header,
466            NativeStatus::BadRequest,
467            "authentication must be a request frame with status OK",
468        );
469    }
470    if header.opcode != NativeOpcode::Authenticate {
471        if let Some(runtime) = &config.production {
472            runtime.record_authentication_failure();
473        }
474        return error_frame(
475            header,
476            NativeStatus::Unauthorized,
477            "authenticate before sending native operations",
478        );
479    }
480    let Some(runtime) = &config.production else {
481        return ok_frame(header, Vec::new());
482    };
483    let Ok(token) = std::str::from_utf8(payload) else {
484        runtime.record_authentication_failure();
485        return error_frame(
486            header,
487            NativeStatus::Unauthorized,
488            "native credential is not valid UTF-8",
489        );
490    };
491    if runtime.authenticates(token) {
492        ok_frame(header, Vec::new())
493    } else {
494        error_frame(
495            header,
496            NativeStatus::Unauthorized,
497            "invalid native production credential",
498        )
499    }
500}
501
502async fn dispatch(
503    header: NativeFrameHeader,
504    payload: Vec<u8>,
505    store: Arc<DurableTelemetryStore>,
506    config: &NativeServerConfig,
507) -> NativeFrame {
508    if matches!(
509        header.opcode,
510        NativeOpcode::Query | NativeOpcode::QueryMetrics | NativeOpcode::QueryTraces
511    ) && let Some(gate) = &config.request_gate
512        && let Err(error) = gate.check_query()
513    {
514        return error_frame(header, NativeStatus::Unavailable, &error);
515    }
516    match header.opcode {
517        NativeOpcode::Ping => ok_frame(header, payload),
518        NativeOpcode::Describe => {
519            if let Some(gate) = &config.request_gate
520                && let Err(error) = gate.check()
521            {
522                return error_frame(header, NativeStatus::Unavailable, &error);
523            }
524            let mut capabilities = NativeCapabilities {
525                protocol_version: 1,
526                append_v1: true,
527                logical_partitions: [
528                    u16::try_from(store.telemetry_partition_count())
529                        .expect("DurableTelemetryStore validates the v1 partition space"),
530                    u16::try_from(store.telemetry_partition_count())
531                        .expect("DurableTelemetryStore validates the v1 partition space"),
532                    u16::try_from(store.telemetry_partition_count())
533                        .expect("DurableTelemetryStore validates the v1 partition space"),
534                ],
535                query_logs: true,
536                query_metrics: true,
537                query_traces: true,
538                query_series: false,
539                append_queryable: config.wait_for_index,
540            };
541            if let Some(gate) = &config.request_gate {
542                capabilities = gate.capabilities(capabilities);
543            }
544            match encode_native_capabilities(&capabilities) {
545                Ok(encoded) => ok_frame(header, encoded),
546                Err(error) => error_frame(header, NativeStatus::Internal, &error.to_string()),
547            }
548        }
549        NativeOpcode::Authenticate => error_frame(
550            header,
551            NativeStatus::BadRequest,
552            "connection is already authenticated",
553        ),
554        NativeOpcode::Append => {
555            let runtime = config.production.clone();
556            let ingest_permit = match runtime.as_ref() {
557                Some(runtime) => match runtime.try_ingest(payload.len()) {
558                    Some(permit) => Some(permit),
559                    None if runtime.lifecycle().state() != ServiceState::Ready => {
560                        return error_frame(
561                            header,
562                            NativeStatus::Unavailable,
563                            "native ingestion is draining or unavailable",
564                        );
565                    }
566                    None => {
567                        return error_frame(
568                            header,
569                            NativeStatus::TooManyRequests,
570                            "native ingest concurrency or rate limit exceeded",
571                        );
572                    }
573                },
574                None => None,
575            };
576            let source_bytes = payload.len();
577            if !is_native_telemetry_batch(&payload) {
578                return error_frame(
579                    header,
580                    NativeStatus::BadRequest,
581                    "native append requires the signal-aware STB1 payload",
582                );
583            }
584            let telemetry_batch = match NativeTelemetryBatch::decode_native_append(&payload) {
585                Ok(batch) => batch,
586                Err(error) => {
587                    return error_frame(header, NativeStatus::BadRequest, &error.to_string());
588                }
589            };
590            if let Some(gate) = &config.request_gate
591                && let Err(error) = gate.check_partitions(&telemetry_batch.partitions)
592            {
593                return error_frame(header, NativeStatus::Unavailable, &error);
594            }
595            if let Some(runtime) = &runtime
596                && telemetry_batch
597                    .partitions
598                    .iter()
599                    .any(|partition| partition.envelope.tenant.as_ref() != runtime.tenant())
600            {
601                return error_frame(
602                    header,
603                    NativeStatus::Unauthorized,
604                    "native telemetry tenant does not match the authenticated tenant",
605                );
606            }
607            let wait_for_index = config.wait_for_index;
608            let payload_digest = blake3::hash(&payload).to_hex().to_string();
609            let retry_id = header.request_id;
610            let append = move || {
611                let records = telemetry_batch
612                    .partitions
613                    .iter()
614                    .fold(0_u32, |total, partition| {
615                        total.saturating_add(partition.envelope.item_count)
616                    });
617                let result = store
618                    .append_validated_telemetry_batch_with_retry_id(
619                        &telemetry_batch,
620                        wait_for_index,
621                        retry_id,
622                        payload_digest,
623                    )
624                    .and_then(|ack| {
625                        ack.encode()
626                            .map(|encoded| (encoded, records))
627                            .map_err(|error| LokiApiError::internal(error.to_string()))
628                    });
629                drop(ingest_permit);
630                result
631            };
632            match tokio::task::spawn_blocking(append).await {
633                Ok(Ok((ack, records))) => {
634                    if let Some(runtime) = &config.production {
635                        runtime.record_ingest(source_bytes, records as usize);
636                    }
637                    ok_frame(header, ack)
638                }
639                Ok(Err(error)) => store_error_frame(header, error),
640                Err(error) => error_frame(
641                    header,
642                    NativeStatus::Internal,
643                    &format!("native append worker failed: {error}"),
644                ),
645            }
646        }
647        NativeOpcode::Query => {
648            let query_permit = match config.production.as_ref() {
649                Some(runtime) => match runtime.try_query() {
650                    Some(permit) => {
651                        runtime.record_query();
652                        Some(permit)
653                    }
654                    None if matches!(
655                        runtime.lifecycle().state(),
656                        ServiceState::Starting | ServiceState::Stopping | ServiceState::Failed
657                    ) =>
658                    {
659                        return error_frame(
660                            header,
661                            NativeStatus::Unavailable,
662                            "native query service is unavailable",
663                        );
664                    }
665                    None => {
666                        return error_frame(
667                            header,
668                            NativeStatus::TooManyRequests,
669                            "native query concurrency limit exceeded",
670                        );
671                    }
672                },
673                None => None,
674            };
675            let query = match decode_native_query(&payload) {
676                Ok(query) => query,
677                Err(error) => {
678                    return error_frame(header, NativeStatus::BadRequest, &error.to_string());
679                }
680            };
681            if config
682                .production
683                .as_ref()
684                .is_some_and(|runtime| query.tenant != runtime.tenant())
685            {
686                return error_frame(
687                    header,
688                    NativeStatus::Unauthorized,
689                    "native query tenant does not match the authenticated tenant",
690                );
691            }
692            let tenant = query.tenant.clone();
693            let query_timeout = config
694                .production
695                .as_ref()
696                .map(|runtime| runtime.query_timeout());
697            let worker = tokio::task::spawn_blocking(move || {
698                let result = store.query_native(&query);
699                drop(query_permit);
700                result
701            });
702            let result = match query_timeout {
703                Some(timeout) => match tokio::time::timeout(timeout, worker).await {
704                    Ok(result) => result,
705                    Err(_) => {
706                        return error_frame(
707                            header,
708                            NativeStatus::Timeout,
709                            "native query deadline exceeded",
710                        );
711                    }
712                },
713                None => worker.await,
714            };
715            match result {
716                Ok(Ok(entries)) => match encode_native_log_query_result(&tenant, entries) {
717                    Ok(encoded) => ok_frame(header, encoded),
718                    Err(error) => error_frame(header, NativeStatus::Internal, &error.to_string()),
719                },
720                Ok(Err(error)) => store_error_frame(header, error),
721                Err(error) => error_frame(
722                    header,
723                    NativeStatus::Internal,
724                    &format!("native query worker failed: {error}"),
725                ),
726            }
727        }
728        NativeOpcode::QueryMetrics => {
729            let query_permit = match config.production.as_ref() {
730                Some(runtime) => match runtime.try_query() {
731                    Some(permit) => {
732                        runtime.record_query();
733                        Some(permit)
734                    }
735                    None if matches!(
736                        runtime.lifecycle().state(),
737                        ServiceState::Starting | ServiceState::Stopping | ServiceState::Failed
738                    ) =>
739                    {
740                        return error_frame(
741                            header,
742                            NativeStatus::Unavailable,
743                            "native query service is unavailable",
744                        );
745                    }
746                    None => {
747                        return error_frame(
748                            header,
749                            NativeStatus::TooManyRequests,
750                            "native query concurrency limit exceeded",
751                        );
752                    }
753                },
754                None => None,
755            };
756            let query = match decode_native_metric_query(&payload) {
757                Ok(query) => query,
758                Err(error) => {
759                    return error_frame(header, NativeStatus::BadRequest, &error.to_string());
760                }
761            };
762            if config
763                .production
764                .as_ref()
765                .is_some_and(|runtime| query.tenant.as_ref() != runtime.tenant())
766            {
767                return error_frame(
768                    header,
769                    NativeStatus::Unauthorized,
770                    "native metric query tenant does not match the authenticated tenant",
771                );
772            }
773            let query_timeout = config
774                .production
775                .as_ref()
776                .map(|runtime| runtime.query_timeout());
777            let worker = tokio::task::spawn_blocking(move || {
778                let result = store.query_metrics(&query);
779                drop(query_permit);
780                result
781            });
782            let result = match query_timeout {
783                Some(timeout) => match tokio::time::timeout(timeout, worker).await {
784                    Ok(result) => result,
785                    Err(_) => {
786                        return error_frame(
787                            header,
788                            NativeStatus::Timeout,
789                            "native metric query deadline exceeded",
790                        );
791                    }
792                },
793                None => worker.await,
794            };
795            match result {
796                Ok(Ok(points)) => match encode_native_metric_query_result(&points) {
797                    Ok(encoded) => ok_frame(header, encoded),
798                    Err(error) => error_frame(header, NativeStatus::Internal, &error.to_string()),
799                },
800                Ok(Err(error)) => store_error_frame(header, error),
801                Err(error) => error_frame(
802                    header,
803                    NativeStatus::Internal,
804                    &format!("native metric query worker failed: {error}"),
805                ),
806            }
807        }
808        NativeOpcode::QueryTraces => {
809            let query_permit = match config.production.as_ref() {
810                Some(runtime) => match runtime.try_query() {
811                    Some(permit) => {
812                        runtime.record_query();
813                        Some(permit)
814                    }
815                    None if matches!(
816                        runtime.lifecycle().state(),
817                        ServiceState::Starting | ServiceState::Stopping | ServiceState::Failed
818                    ) =>
819                    {
820                        return error_frame(
821                            header,
822                            NativeStatus::Unavailable,
823                            "native query service is unavailable",
824                        );
825                    }
826                    None => {
827                        return error_frame(
828                            header,
829                            NativeStatus::TooManyRequests,
830                            "native query concurrency limit exceeded",
831                        );
832                    }
833                },
834                None => None,
835            };
836            let query = match decode_native_trace_query(&payload) {
837                Ok(query) => query,
838                Err(error) => {
839                    return error_frame(header, NativeStatus::BadRequest, &error.to_string());
840                }
841            };
842            if config
843                .production
844                .as_ref()
845                .is_some_and(|runtime| query.tenant.as_ref() != runtime.tenant())
846            {
847                return error_frame(
848                    header,
849                    NativeStatus::Unauthorized,
850                    "native trace query tenant does not match the authenticated tenant",
851                );
852            }
853            let query_timeout = config
854                .production
855                .as_ref()
856                .map(|runtime| runtime.query_timeout());
857            let worker = tokio::task::spawn_blocking(move || {
858                let result = store.query_traces(&query);
859                drop(query_permit);
860                result
861            });
862            let result = match query_timeout {
863                Some(timeout) => match tokio::time::timeout(timeout, worker).await {
864                    Ok(result) => result,
865                    Err(_) => {
866                        return error_frame(
867                            header,
868                            NativeStatus::Timeout,
869                            "native trace query deadline exceeded",
870                        );
871                    }
872                },
873                None => worker.await,
874            };
875            match result {
876                Ok(Ok(spans)) => match encode_native_trace_query_result(&spans) {
877                    Ok(encoded) => ok_frame(header, encoded),
878                    Err(error) => error_frame(header, NativeStatus::Internal, &error.to_string()),
879                },
880                Ok(Err(error)) => store_error_frame(header, error),
881                Err(error) => error_frame(
882                    header,
883                    NativeStatus::Internal,
884                    &format!("native trace query worker failed: {error}"),
885                ),
886            }
887        }
888    }
889}
890
891fn ok_frame(header: NativeFrameHeader, payload: Vec<u8>) -> NativeFrame {
892    NativeFrame::response(header.opcode, header.request_id, NativeStatus::Ok, payload)
893        .expect("bounded request produced a bounded response")
894}
895
896fn store_error_frame(header: NativeFrameHeader, error: LokiApiError) -> NativeFrame {
897    let status = match error.status() {
898        axum::http::StatusCode::BAD_REQUEST => NativeStatus::BadRequest,
899        axum::http::StatusCode::UNAUTHORIZED | axum::http::StatusCode::FORBIDDEN => {
900            NativeStatus::Unauthorized
901        }
902        axum::http::StatusCode::SERVICE_UNAVAILABLE => NativeStatus::Unavailable,
903        axum::http::StatusCode::TOO_MANY_REQUESTS => NativeStatus::TooManyRequests,
904        _ => NativeStatus::Internal,
905    };
906    error_frame(header, status, &error.to_string())
907}
908
909fn error_frame(header: NativeFrameHeader, status: NativeStatus, message: &str) -> NativeFrame {
910    let mut payload = message.as_bytes();
911    if payload.len() > 4_096 {
912        payload = &payload[..4_096];
913    }
914    NativeFrame::response(header.opcode, header.request_id, status, payload.to_vec())
915        .expect("error payload is bounded")
916}
917
918fn invalid_data(error: impl std::fmt::Display) -> io::Error {
919    io::Error::new(io::ErrorKind::InvalidData, error.to_string())
920}
921
922#[cfg(test)]
923mod tests {
924    use std::collections::BTreeMap;
925    use std::fs;
926    use std::time::{SystemTime, UNIX_EPOCH};
927
928    use shard_stream_core::{LogicalPartitionId, TopicPartition};
929    use tokio::net::TcpStream;
930
931    use super::*;
932    use crate::{
933        DurableTelemetryConfig, LokiEntry, NativeLogQueryResult, NativePartitionAppend,
934        NativeQuery, NativeQueryDirection, NativeTelemetryAppendAck, NativeTelemetryBatch,
935        ServiceLifecycle, SingleTenantConfig, StripeConfig, decode_native_log_query_result,
936        encode_native_query, prepare_loki_log_envelope,
937    };
938
939    #[derive(Debug)]
940    struct DenyGate;
941
942    impl NativeRequestGate for DenyGate {
943        fn check(&self) -> Result<(), String> {
944            Err("not the current leader".into())
945        }
946    }
947
948    #[test]
949    fn native_server_rejects_an_inbound_budget_smaller_than_one_frame() {
950        let config = NativeServerConfig {
951            max_frame_bytes: 1024,
952            max_inbound_bytes_total: 1023,
953            ..NativeServerConfig::default()
954        };
955        let error = config.validate().expect_err("invalid inbound budget");
956        assert!(
957            error
958                .to_string()
959                .contains("total inbound bytes must cover one frame")
960        );
961    }
962
963    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
964    async fn native_server_reserves_global_input_before_reading_a_frame_body() {
965        let nonce = SystemTime::now()
966            .duration_since(UNIX_EPOCH)
967            .expect("clock")
968            .as_nanos();
969        let directory = std::env::temp_dir().join(format!(
970            "shard-telemetry-native-input-budget-{}-{nonce}",
971            std::process::id()
972        ));
973        let store = Arc::new(
974            DurableTelemetryStore::open(DurableTelemetryConfig {
975                data_directory: directory.clone(),
976                object_store_directory: None,
977                s3_object_store: None,
978                recovery_journal: false,
979                retention: None,
980                shard_count: 1,
981                tenant_partitions: 1,
982                append_linger: std::time::Duration::from_micros(250),
983                stripe: StripeConfig::default(),
984                indexed_ack_timeout: std::time::Duration::from_secs(30),
985            })
986            .expect("store"),
987        );
988        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
989        let address = listener.local_addr().expect("address");
990        let (stop, stopped) = tokio::sync::oneshot::channel();
991        let server_store = Arc::clone(&store);
992        let server = tokio::spawn(async move {
993            serve_native(
994                listener,
995                server_store,
996                NativeServerConfig {
997                    max_frame_bytes: 16,
998                    max_inbound_bytes_total: 16,
999                    ..NativeServerConfig::default()
1000                },
1001                async {
1002                    let _ = stopped.await;
1003                },
1004            )
1005            .await
1006        });
1007
1008        let header = NativeFrameHeader::request(NativeOpcode::Ping, 1, &[0; 16])
1009            .expect("header")
1010            .encode();
1011        let mut first = TcpStream::connect(address).await.expect("first connect");
1012        first.write_all(&header).await.expect("first header");
1013        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
1014        let mut second = TcpStream::connect(address).await.expect("second connect");
1015        second.write_all(&header).await.expect("second header");
1016        let mut closed = [0_u8; 1];
1017        let read =
1018            tokio::time::timeout(std::time::Duration::from_secs(1), second.read(&mut closed))
1019                .await
1020                .expect("inbound budget closes excess connection")
1021                .expect("read");
1022        assert_eq!(read, 0);
1023
1024        drop(first);
1025        stop.send(()).expect("stop");
1026        server
1027            .await
1028            .expect("server joins")
1029            .expect("server succeeds");
1030        drop(store);
1031        fs::remove_dir_all(directory).expect("cleanup");
1032    }
1033
1034    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1035    async fn tcp_protocol_pings_appends_and_queries_with_request_ids() {
1036        let nonce = SystemTime::now()
1037            .duration_since(UNIX_EPOCH)
1038            .expect("clock")
1039            .as_nanos();
1040        let directory = std::env::temp_dir().join(format!(
1041            "shard-telemetry-native-server-{}-{nonce}",
1042            std::process::id()
1043        ));
1044        let store = Arc::new(
1045            DurableTelemetryStore::open(DurableTelemetryConfig {
1046                data_directory: directory.clone(),
1047                object_store_directory: None,
1048                s3_object_store: None,
1049                recovery_journal: false,
1050                retention: None,
1051                shard_count: 2,
1052                tenant_partitions: 8,
1053                append_linger: std::time::Duration::from_micros(250),
1054                stripe: StripeConfig::default(),
1055                indexed_ack_timeout: std::time::Duration::from_secs(30),
1056            })
1057            .expect("store"),
1058        );
1059        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
1060        let address = listener.local_addr().expect("address");
1061        let (stop, stopped) = tokio::sync::oneshot::channel();
1062        let server_store = Arc::clone(&store);
1063        let server = tokio::spawn(async move {
1064            serve_native(
1065                listener,
1066                server_store,
1067                NativeServerConfig::default(),
1068                async {
1069                    let _ = stopped.await;
1070                },
1071            )
1072            .await
1073        });
1074        let mut client = TcpStream::connect(address).await.expect("connect");
1075
1076        let ping = NativeFrame::request(NativeOpcode::Ping, 7, b"hello".to_vec()).expect("ping");
1077        write_frame(&mut client, &ping).await;
1078        let response = read_frame(&mut client).await;
1079        assert_eq!(response.header.request_id, 7);
1080        assert_eq!(response.header.status, NativeStatus::Ok);
1081        assert_eq!(response.payload, b"hello");
1082
1083        let entry = LokiEntry {
1084            timestamp_unix_nanos: 100,
1085            labels: BTreeMap::from([("app".to_owned(), "api".to_owned())]),
1086            line: "native timeout".to_owned(),
1087            structured_metadata: BTreeMap::from([("trace".to_owned(), "abc".to_owned())]),
1088        };
1089        let topic_partition = TopicPartition::new(crate::LOGS_TOPIC_ID, LogicalPartitionId::new(0));
1090        let batch = NativeTelemetryBatch {
1091            partitions: vec![NativePartitionAppend {
1092                topic_partition,
1093                envelope: prepare_loki_log_envelope("tenant-a", vec![entry.clone()])
1094                    .expect("log envelope"),
1095                transient_context: None,
1096            }],
1097        }
1098        .encode()
1099        .expect("batch");
1100        let append = NativeFrame::request(NativeOpcode::Append, 8, batch).expect("append");
1101        write_frame(&mut client, &append).await;
1102        let response = read_frame(&mut client).await;
1103        assert_eq!(response.header.request_id, 8);
1104        assert_eq!(response.header.status, NativeStatus::Ok);
1105        assert_eq!(
1106            NativeTelemetryAppendAck::decode(&response.payload)
1107                .expect("ack")
1108                .partitions[0]
1109                .first_offset,
1110            0
1111        );
1112
1113        // A retry after a lost acknowledgement uses the same native request
1114        // ID. It must return the original receipt rather than append a second
1115        // copy of the log event.
1116        write_frame(&mut client, &append).await;
1117        let retry = read_frame(&mut client).await;
1118        assert_eq!(retry.header.status, NativeStatus::Ok);
1119        assert_eq!(retry.payload, response.payload);
1120
1121        let query = NativeQuery {
1122            tenant: "tenant-a".to_owned(),
1123            labels: BTreeMap::from([("app".to_owned(), "api".to_owned())]),
1124            terms: vec!["timeout".to_owned()],
1125            start_timestamp_unix_nanos: None,
1126            end_timestamp_unix_nanos: None,
1127            limit: 10,
1128            direction: NativeQueryDirection::OldestFirst,
1129        };
1130        let query = NativeFrame::request(
1131            NativeOpcode::Query,
1132            9,
1133            encode_native_query(&query).expect("query"),
1134        )
1135        .expect("query frame");
1136        write_frame(&mut client, &query).await;
1137        let response = read_frame(&mut client).await;
1138        assert_eq!(response.header.request_id, 9);
1139        assert_eq!(response.header.status, NativeStatus::Ok);
1140        let NativeLogQueryResult { tenant, entries } =
1141            decode_native_log_query_result(&response.payload).expect("results");
1142        assert_eq!(tenant, "tenant-a");
1143        assert_eq!(entries, vec![entry]);
1144
1145        drop(client);
1146        stop.send(()).expect("stop");
1147        server
1148            .await
1149            .expect("server joins")
1150            .expect("server succeeds");
1151        drop(store);
1152        fs::remove_dir_all(directory).expect("cleanup");
1153    }
1154
1155    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1156    async fn production_native_protocol_requires_authentication_before_operations() {
1157        let nonce = SystemTime::now()
1158            .duration_since(UNIX_EPOCH)
1159            .expect("clock")
1160            .as_nanos();
1161        let directory = std::env::temp_dir().join(format!(
1162            "shard-telemetry-native-auth-{}-{nonce}",
1163            std::process::id()
1164        ));
1165        let store = Arc::new(
1166            DurableTelemetryStore::open(DurableTelemetryConfig {
1167                data_directory: directory.clone(),
1168                object_store_directory: None,
1169                s3_object_store: None,
1170                recovery_journal: false,
1171                retention: None,
1172                shard_count: 1,
1173                tenant_partitions: 1,
1174                append_linger: std::time::Duration::from_micros(250),
1175                stripe: StripeConfig::default(),
1176                indexed_ack_timeout: std::time::Duration::from_secs(30),
1177            })
1178            .expect("store"),
1179        );
1180        let lifecycle = Arc::new(ServiceLifecycle::new());
1181        lifecycle.mark_ready();
1182        let runtime = Arc::new(
1183            ProductionRuntime::new(
1184                SingleTenantConfig {
1185                    tenant: Arc::from("tenant-a"),
1186                    bearer_token: Arc::from("0123456789abcdef"),
1187                    max_http_in_flight: 4,
1188                    max_ingest_in_flight: 2,
1189                    max_query_in_flight: 2,
1190                    ingest_bytes_per_second: 0,
1191                    ingest_burst_bytes: 0,
1192                    max_tail_subscribers: 1,
1193                    max_native_connections: 4,
1194                    query_timeout: std::time::Duration::from_secs(30),
1195                    native_auth_timeout: std::time::Duration::from_millis(50),
1196                },
1197                lifecycle,
1198            )
1199            .expect("runtime"),
1200        );
1201        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
1202        let address = listener.local_addr().expect("address");
1203        let (stop, stopped) = tokio::sync::oneshot::channel();
1204        let server_store = Arc::clone(&store);
1205        let server = tokio::spawn(async move {
1206            serve_native(
1207                listener,
1208                server_store,
1209                NativeServerConfig {
1210                    production: Some(runtime),
1211                    request_gate: Some(Arc::new(DenyGate)),
1212                    ..NativeServerConfig::default()
1213                },
1214                async {
1215                    let _ = stopped.await;
1216                },
1217            )
1218            .await
1219        });
1220
1221        let mut idle = TcpStream::connect(address).await.expect("idle connect");
1222        let mut closed = [0_u8; 1];
1223        let read = tokio::time::timeout(std::time::Duration::from_secs(1), idle.read(&mut closed))
1224            .await
1225            .expect("authentication deadline closes idle connection")
1226            .expect("idle read");
1227        assert_eq!(read, 0);
1228
1229        let mut unauthenticated = TcpStream::connect(address).await.expect("connect");
1230        let ping = NativeFrame::request(NativeOpcode::Ping, 1, b"hello".to_vec()).expect("ping");
1231        write_frame(&mut unauthenticated, &ping).await;
1232        let response = read_frame(&mut unauthenticated).await;
1233        assert_eq!(response.header.status, NativeStatus::Unauthorized);
1234
1235        let mut client = TcpStream::connect(address).await.expect("connect");
1236        let authenticate =
1237            NativeFrame::request(NativeOpcode::Authenticate, 2, b"0123456789abcdef".to_vec())
1238                .expect("authenticate");
1239        write_frame(&mut client, &authenticate).await;
1240        let response = read_frame(&mut client).await;
1241        assert_eq!(response.header.request_id, 2);
1242        assert_eq!(response.header.status, NativeStatus::Ok);
1243
1244        let ping = NativeFrame::request(NativeOpcode::Ping, 3, b"ready".to_vec()).expect("ping");
1245        write_frame(&mut client, &ping).await;
1246        let response = read_frame(&mut client).await;
1247        assert_eq!(response.header.request_id, 3);
1248        assert_eq!(response.header.status, NativeStatus::Ok);
1249        assert_eq!(response.payload, b"ready");
1250
1251        let query = NativeFrame::request(NativeOpcode::Query, 4, Vec::new()).expect("query");
1252        write_frame(&mut client, &query).await;
1253        let response = read_frame(&mut client).await;
1254        assert_eq!(response.header.request_id, 4);
1255        assert_eq!(response.header.status, NativeStatus::Unavailable);
1256        assert_eq!(response.payload, b"not the current leader");
1257
1258        drop(unauthenticated);
1259        drop(client);
1260        stop.send(()).expect("stop");
1261        server
1262            .await
1263            .expect("server joins")
1264            .expect("server succeeds");
1265        drop(store);
1266        fs::remove_dir_all(directory).expect("cleanup");
1267    }
1268
1269    async fn write_frame(stream: &mut TcpStream, frame: &NativeFrame) {
1270        stream
1271            .write_all(&frame.header.encode())
1272            .await
1273            .expect("header");
1274        stream.write_all(&frame.payload).await.expect("payload");
1275    }
1276
1277    async fn read_frame(stream: &mut TcpStream) -> NativeFrame {
1278        let mut header = [0; NATIVE_FRAME_HEADER_BYTES];
1279        stream.read_exact(&mut header).await.expect("header");
1280        let header = NativeFrameHeader::decode(&header).expect("decode header");
1281        let mut payload = vec![0; header.payload_len as usize];
1282        stream.read_exact(&mut payload).await.expect("payload");
1283        header.verify_payload(&payload).expect("checksum");
1284        NativeFrame { header, payload }
1285    }
1286}