appcore-api 1.0.3-rc

HTTP API host and transport contracts for AppCore Runtime.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

// =============================================================================
//        #######
//     ###       ###     F: query_contract.rs
//    ##   ## ##   ##    P: AppCore-Runtime
//         ## ##
//                       C: 2026/06/01 13:57:57 by dnettoRaw
//    ##   ## ##   ##    U: 2026/07/23 13:45:20 by dnettoRaw
//      ###########      S: 1.0.1-rc.8
// =============================================================================

//! Shared query request/response API contract for transports.

use serde::{Deserialize, Serialize};
use std::io::{self, Write};

/// Version 1 side-effect-free query request.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct QueryRequest {
    /// Declared application or Runtime query capability.
    pub query_name: String,
    /// Caller-assigned request identity.
    pub query_id: String,
    /// Structured application-owned query payload.
    pub payload: serde_json::Value,
}

/// Version 1 controlled query response.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct QueryResponse {
    /// Whether query execution succeeded.
    pub ok: bool,
    /// Controlled rejection detail, when present.
    pub message: Option<String>,
    /// Structured application-owned response payload.
    pub payload: serde_json::Value,
}

/// Validation failures defined by the query V1 contract.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum QueryRequestValidationError {
    /// The query name is empty.
    EmptyQueryName,
    /// The query identifier is empty.
    EmptyQueryId,
    /// The query name is malformed.
    InvalidQueryName,
    /// The query identifier is malformed.
    InvalidQueryId,
    /// The serialized payload exceeds the configured request bound.
    PayloadTooLarge,
}

impl QueryRequest {
    /// Validates identifiers and the serialized payload bound.
    pub fn validate(&self, max_payload_bytes: usize) -> Result<(), QueryRequestValidationError> {
        if self.query_name.trim().is_empty() {
            return Err(QueryRequestValidationError::EmptyQueryName);
        }
        if self.query_id.trim().is_empty() {
            return Err(QueryRequestValidationError::EmptyQueryId);
        }
        if self.query_name.len() > 128 || !is_valid_token(&self.query_name) {
            return Err(QueryRequestValidationError::InvalidQueryName);
        }
        if self.query_id.len() > 128 || !is_valid_token(&self.query_id) {
            return Err(QueryRequestValidationError::InvalidQueryId);
        }
        if !payload_fits(&self.payload, max_payload_bytes) {
            return Err(QueryRequestValidationError::PayloadTooLarge);
        }
        Ok(())
    }

    /// Serializes the structured payload to JSON bytes.
    pub fn payload_bytes(&self) -> Vec<u8> {
        serde_json::to_vec(&self.payload).unwrap_or_default()
    }
}

struct LimitedJsonCounter {
    remaining: usize,
    exceeded: bool,
}

impl LimitedJsonCounter {
    const fn new(limit: usize) -> Self {
        Self {
            remaining: limit,
            exceeded: false,
        }
    }
}

impl Write for LimitedJsonCounter {
    fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
        if bytes.len() > self.remaining {
            self.exceeded = true;
            return Err(io::Error::other("query payload exceeds configured limit"));
        }
        self.remaining -= bytes.len();
        Ok(bytes.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}

fn payload_fits(payload: &serde_json::Value, limit: usize) -> bool {
    let mut counter = LimitedJsonCounter::new(limit);
    let result = serde_json::to_writer(&mut counter, payload);
    debug_assert!(result.is_ok() || counter.exceeded);
    !counter.exceeded
}

impl QueryResponse {
    /// Creates a successful response with a structured payload.
    pub fn ok(payload: serde_json::Value) -> Self {
        Self {
            ok: true,
            message: None,
            payload,
        }
    }

    /// Creates a controlled rejected response.
    pub fn rejected(message: impl Into<String>) -> Self {
        Self {
            ok: false,
            message: Some(message.into()),
            payload: serde_json::Value::Object(serde_json::Map::new()),
        }
    }
}

fn is_valid_token(value: &str) -> bool {
    value
        .bytes()
        .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b':' | b'-'))
}

#[cfg(test)]
#[path = "query_contract_tests.rs"]
mod tests;