agentics_contracts/validation/
public_api.rs

1//! Shared validation for public read API query contracts.
2
3use agentics_domain::models::challenge::ChallengeBundleSpec;
4use agentics_domain::models::names::{ChallengeKeyword, TargetName};
5use agentics_error::{Result, ServiceError};
6
7/// Default public challenge catalog page size.
8pub const DEFAULT_PUBLIC_CHALLENGE_LIST_LIMIT: i64 = 100;
9/// Default visible public solution submission page size.
10pub const DEFAULT_PUBLIC_SUBMISSION_LIST_LIMIT: i64 = 20;
11/// Default leaderboard page size.
12pub const DEFAULT_PUBLIC_LEADERBOARD_LIMIT: i64 = 50;
13/// Maximum page size for public list-style reads.
14pub const MAX_PUBLIC_LIST_LIMIT: i64 = 100;
15
16/// Bounded pagination parameters for a public collection endpoint.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct PublicPagination {
19    pub limit: i64,
20    pub offset: i64,
21}
22
23/// Validated public challenge catalog query.
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct PublicChallengeCatalogQuery {
26    pub limit: i64,
27    pub offset: i64,
28    pub search: Option<String>,
29    pub keywords: Vec<ChallengeKeyword>,
30}
31
32impl PublicChallengeCatalogQuery {
33    /// Parse and validate the public challenge catalog query contract.
34    pub fn try_from_raw_parts(
35        limit: Option<&str>,
36        offset: Option<&str>,
37        search: Option<String>,
38        keywords: Vec<String>,
39    ) -> Result<Self> {
40        let limit = parse_optional_i64(limit, "limit")?;
41        let offset = parse_optional_i64(offset, "offset")?;
42        let page = public_pagination(
43            limit,
44            offset,
45            DEFAULT_PUBLIC_CHALLENGE_LIST_LIMIT,
46            "challenge list",
47        )?;
48        Ok(Self {
49            limit: page.limit,
50            offset: page.offset,
51            search: normalized_challenge_search(search.as_deref())?,
52            keywords: parse_challenge_keywords(keywords)?,
53        })
54    }
55}
56
57fn parse_optional_i64(value: Option<&str>, field: &str) -> Result<Option<i64>> {
58    value
59        .map(|value| {
60            value
61                .parse::<i64>()
62                .map_err(|_| ServiceError::BadRequest(format!("{field} must be an integer")))
63        })
64        .transpose()
65}
66
67fn parse_challenge_keywords(raw: Vec<String>) -> Result<Vec<ChallengeKeyword>> {
68    if raw.len() > 6 {
69        return Err(ServiceError::Validation(
70            "challenge catalog filters accept at most 6 keywords".to_string(),
71        ));
72    }
73    raw.into_iter()
74        .map(ChallengeKeyword::try_new)
75        .collect::<std::result::Result<Vec<_>, _>>()
76        .map_err(|e| ServiceError::Validation(e.to_string()))
77}
78
79fn normalized_challenge_search(raw: Option<&str>) -> Result<Option<String>> {
80    let Some(raw) = raw else {
81        return Ok(None);
82    };
83    let normalized = raw.trim();
84    if normalized.is_empty() {
85        return Ok(None);
86    }
87    if normalized.len() > 120 || normalized.chars().any(char::is_control) {
88        return Err(ServiceError::Validation(
89            "challenge search query must be at most 120 UTF-8 bytes and contain no control characters"
90                .to_string(),
91        ));
92    }
93    Ok(Some(normalized.to_string()))
94}
95
96/// Validate a public list limit without silently widening expensive reads.
97pub fn bounded_public_limit(
98    requested: Option<i64>,
99    default_limit: i64,
100    label: &str,
101) -> Result<i64> {
102    let limit = requested.unwrap_or(default_limit);
103    if !(1..=MAX_PUBLIC_LIST_LIMIT).contains(&limit) {
104        return Err(ServiceError::BadRequest(format!(
105            "{label} limit must be between 1 and {MAX_PUBLIC_LIST_LIMIT}"
106        )));
107    }
108    Ok(limit)
109}
110
111/// Validate a public list offset without allowing negative pagination cursors.
112pub fn bounded_public_offset(requested: Option<i64>, label: &str) -> Result<i64> {
113    let offset = requested.unwrap_or(0);
114    if offset < 0 {
115        return Err(ServiceError::BadRequest(format!(
116            "{label} offset must be greater than or equal to 0"
117        )));
118    }
119    Ok(offset)
120}
121
122/// Validate limit and offset together for public list endpoints.
123pub fn public_pagination(
124    requested_limit: Option<i64>,
125    requested_offset: Option<i64>,
126    default_limit: i64,
127    label: &str,
128) -> Result<PublicPagination> {
129    Ok(PublicPagination {
130        limit: bounded_public_limit(requested_limit, default_limit, label)?,
131        offset: bounded_public_offset(requested_offset, label)?,
132    })
133}
134
135/// Resolve an explicit public target query against the challenge spec.
136pub fn resolve_required_public_target(
137    spec: &ChallengeBundleSpec,
138    requested_target: Option<&str>,
139) -> Result<TargetName> {
140    let Some(target) = requested_target else {
141        return Err(ServiceError::BadRequest(
142            "target query parameter is required".to_string(),
143        ));
144    };
145    let target = target
146        .parse::<TargetName>()
147        .map_err(|e| ServiceError::BadRequest(e.to_string()))?;
148    if spec.target(&target).is_some() {
149        return Ok(target);
150    }
151    Err(ServiceError::BadRequest(format!(
152        "challenge does not support target `{target}`"
153    )))
154}
155
156/// Resolve an optional public target filter against the challenge spec.
157pub fn resolve_optional_public_target(
158    spec: &ChallengeBundleSpec,
159    requested_target: Option<&str>,
160) -> Result<Option<TargetName>> {
161    requested_target
162        .map(|target| resolve_required_public_target(spec, Some(target)))
163        .transpose()
164}
165
166#[cfg(test)]
167mod tests {
168    use crate::zip_project::ZIP_PROJECT_PROTOCOL;
169    use agentics_domain::models::challenge::{
170        ChallengeBundleSpec, ChallengeEligibilitySpec, ChallengeEligibilityType,
171        ChallengeExecutionSpec, ChallengeSolutionPublicationPolicy, ChallengeVisibility,
172        ChallengeVisibilitySpec, DatasetsSpec, EvaluatorSpec, PrivateBenchmarkPolicy,
173        PublicChallengeBundleSpec, SeparatedEvaluatorExecutionSpec, SolutionSpec,
174    };
175    use agentics_domain::models::evaluation::ScoreVisibility;
176    use agentics_domain::models::localization::LocalizedText;
177    use agentics_domain::models::names::{ChallengeKeyword, ChallengeName, TargetName};
178    use agentics_domain::models::paths::BundleRelativePath;
179
180    use super::{
181        DEFAULT_PUBLIC_CHALLENGE_LIST_LIMIT, PublicChallengeCatalogQuery, bounded_public_limit,
182        public_pagination, resolve_required_public_target,
183    };
184
185    fn target_name(value: &str) -> TargetName {
186        TargetName::try_new(value.to_string()).expect("target")
187    }
188
189    fn challenge_keyword(value: &str) -> ChallengeKeyword {
190        ChallengeKeyword::try_new(value.to_string()).expect("keyword")
191    }
192
193    fn spec() -> ChallengeBundleSpec {
194        let public: PublicChallengeBundleSpec =
195            serde_json::from_value(serde_json::json!({
196                "schema_version": 1,
197                "challenge_name": "sample-sum",
198                "challenge_title": "Sample Sum",
199                "summary": {"en": "Sum numbers", "zh": "Sum numbers zh"},
200                "keywords": ["arithmetic"],
201                "solution": {"protocol": ZIP_PROJECT_PROTOCOL, "manifest_file": "agentics.solution.json"},
202                "targets": [{
203                    "name": "linux-arm64-cpu",
204                    "docker_platform": "linux/arm64",
205                    "accelerator": null,
206                    "validation_enabled": true,
207                    "resource_profile": {
208                        "name": "agentics-small",
209                        "solution_image": {"source": "local", "reference": "agentics-linux-arm64-cpu:ubuntu26.04-local"},
210                        "evaluator_image": {"source": "local", "reference": "agentics-linux-arm64-cpu:ubuntu26.04-local"},
211                        "solution": {
212                            "setup": {"timeout_sec": 30, "memory_limit_mb": 512, "cpu_limit_millis": 1000, "disk_limit_mb": 1024, "network_access": "disabled"},
213                            "build": {"timeout_sec": 30, "memory_limit_mb": 512, "cpu_limit_millis": 1000, "disk_limit_mb": 1024, "network_access": "disabled"},
214                            "run": {"timeout_sec": 30, "memory_limit_mb": 512, "cpu_limit_millis": 1000, "disk_limit_mb": 1024, "network_access": "disabled"}
215                        },
216                        "evaluator": {
217                            "setup": {"timeout_sec": 30, "memory_limit_mb": 512, "cpu_limit_millis": 1000, "disk_limit_mb": 1024, "network_access": "disabled"},
218                            "run": {"timeout_sec": 30, "memory_limit_mb": 512, "cpu_limit_millis": 1000, "disk_limit_mb": 1024, "network_access": "disabled"}
219                        }
220                    }
221                }],
222                "starts_at": "2026-01-01T00:00:00Z",
223                "eligibility": {"type": "open"},
224                "visibility": {
225                    "leaderboard": "public_live",
226                    "score_distribution": "public_live",
227                    "result_detail": "submitter_live_public_live"
228                },
229                "solution_publication": "private",
230                "execution": {
231                    "mode": "separated_evaluator",
232                    "separated_evaluator": {"command": ["python", "separated-evaluator/run.py"], "result_file": "result.json"}
233                },
234                "datasets": {
235                    "public_dir": "public",
236                    "public_policy": "full",
237                    "private_benchmark_policy": "score_only",
238                    "private_benchmark_enabled": false
239                },
240                "metric_schema": {
241                    "metrics": [{"name": "score", "label": "Score", "direction": "maximize", "visibility": "public"}],
242                    "ranking": {"primary_metric_name": "score"}
243                }
244            }))
245            .expect("fixture should deserialize");
246        ChallengeBundleSpec {
247            schema_version: public.schema_version,
248            challenge_name: ChallengeName::try_new("sample-sum".to_string()).expect("name"),
249            challenge_title: public.challenge_title,
250            summary: LocalizedText {
251                en: "Sum numbers".to_string(),
252                zh: "Sum numbers zh".to_string(),
253            },
254            keywords: vec![challenge_keyword("arithmetic")],
255            solution: SolutionSpec {
256                protocol: ZIP_PROJECT_PROTOCOL.to_string(),
257                manifest_file: BundleRelativePath::try_new("agentics.solution.json")
258                    .expect("path"),
259            },
260            targets: public.targets,
261            starts_at: "2026-01-01T00:00:00Z".to_string(),
262            closes_at: None,
263            eligibility: ChallengeEligibilitySpec {
264                eligibility_type: ChallengeEligibilityType::Open,
265            },
266            validation_submission_limit: None,
267            official_submission_limit: None,
268            visibility: ChallengeVisibilitySpec {
269                leaderboard: ChallengeVisibility::PublicLive,
270                score_distribution: ChallengeVisibility::PublicLive,
271                result_detail:
272                    agentics_domain::models::challenge::ChallengeResultDetailVisibility::SubmitterLivePublicLive,
273            },
274            solution_publication: ChallengeSolutionPublicationPolicy::Private,
275            execution: ChallengeExecutionSpec::SeparatedEvaluator(SeparatedEvaluatorExecutionSpec {
276                separated_evaluator: EvaluatorSpec {
277                    command: vec!["python".to_string(), "separated-evaluator/run.py".to_string()],
278                    result_file: BundleRelativePath::try_new("result.json").expect("path"),
279                },
280                validation_runs: None,
281                validation_setup: None,
282                official_runs: None,
283                official_evaluation_setup: None,
284            }),
285            datasets: DatasetsSpec {
286                public_dir: BundleRelativePath::try_new("public").expect("path"),
287                private_benchmark_dir: None,
288                public_policy: ScoreVisibility::Full,
289                private_benchmark_policy: PrivateBenchmarkPolicy::ScoreOnly,
290                private_benchmark_enabled: false,
291            },
292            metric_schema: public.metric_schema,
293        }
294    }
295
296    #[test]
297    fn validates_public_pagination() {
298        let page = public_pagination(
299            None,
300            None,
301            DEFAULT_PUBLIC_CHALLENGE_LIST_LIMIT,
302            "challenge list",
303        )
304        .expect("default page should validate");
305        assert_eq!(page.limit, 100);
306        assert_eq!(page.offset, 0);
307        assert!(bounded_public_limit(Some(0), 100, "items").is_err());
308        assert!(public_pagination(Some(1), Some(-1), 100, "items").is_err());
309    }
310
311    #[test]
312    fn validates_public_challenge_catalog_queries() {
313        let query = PublicChallengeCatalogQuery::try_from_raw_parts(
314            Some("25"),
315            Some("5"),
316            Some("  matrix  ".to_string()),
317            vec!["systems".to_string(), "math".to_string()],
318        )
319        .expect("catalog query should validate");
320        assert_eq!(query.limit, 25);
321        assert_eq!(query.offset, 5);
322        assert_eq!(query.search.as_deref(), Some("matrix"));
323        assert_eq!(query.keywords.len(), 2);
324
325        assert!(
326            PublicChallengeCatalogQuery::try_from_raw_parts(Some("abc"), None, None, Vec::new())
327                .is_err()
328        );
329        assert!(
330            PublicChallengeCatalogQuery::try_from_raw_parts(
331                None,
332                None,
333                Some("x".repeat(121)),
334                Vec::new()
335            )
336            .is_err()
337        );
338        assert!(
339            PublicChallengeCatalogQuery::try_from_raw_parts(
340                None,
341                None,
342                None,
343                vec![
344                    "one".to_string(),
345                    "two".to_string(),
346                    "three".to_string(),
347                    "four".to_string(),
348                    "five".to_string(),
349                    "six".to_string(),
350                    "seven".to_string(),
351                ],
352            )
353            .is_err()
354        );
355    }
356
357    #[test]
358    fn resolves_required_public_target() {
359        let spec = spec();
360        assert_eq!(
361            resolve_required_public_target(&spec, Some("linux-arm64-cpu")).expect("target"),
362            target_name("linux-arm64-cpu")
363        );
364        assert!(resolve_required_public_target(&spec, None).is_err());
365        assert!(resolve_required_public_target(&spec, Some("linux-arm64-cuda")).is_err());
366    }
367}
agentics_contracts/validation/public_api.rs

agentics_contracts/validation/
public_api.rs
