Skip to main content

tsurara_sample/
lib.rs

1//! Sample values from the model (design.md 18.7.1): one JSON value per declaration and per
2//! operation parameter, request body and response body, for mocks in every language. The values are
3//! deterministic: they come from the definition (examples, defaults, constraints) and from JSON
4//! Pointers, never from a clock or a random source.
5//!
6//! Published for backends outside this repository, with one version for all tsurara crates,
7//! released with the CLI and moving with `semVersion`. Stable: the sample functions.
8
9use serde_json::{Map, Value, json};
10use std::collections::HashMap;
11use tsurara_loader::Loc;
12use tsurara_sem::ir::{Doc, Literal, ScalarKind, Type};
13use tsurara_sem::naming::NameId;
14use tsurara_sem::operation::{BodyKind, MediaContent, Operation, ParamIn};
15use tsurara_sem::schema::TypeDecl;
16use tsurara_sem::{Model, Warning, WarningKind};
17
18/// How many times a declaration may be entered while sampling one value. A reference that would enter
19/// it again is left out where optional, and becomes `{}` with a `sample-cycle` warning where required.
20const MAX_DEPTH: usize = 2;
21
22#[derive(Debug, Clone, PartialEq, serde::Serialize)]
23#[serde(rename_all = "camelCase")]
24pub struct Samples {
25    /// One value per declaration of the model that has one, in model order.
26    pub types: Vec<(NameId, Value)>,
27    /// One entry per operation, in model order.
28    pub operations: Vec<OperationSamples>,
29}
30
31#[derive(Debug, Clone, PartialEq, serde::Serialize)]
32#[serde(rename_all = "camelCase")]
33pub struct OperationSamples {
34    pub operation_id: String,
35    /// Every parameter that has a value, in definition order.
36    pub params: Vec<ParamSample>,
37    /// The request body, in the first media type that has a value.
38    pub body: Option<BodySample>,
39    /// Each documented response body, by status and media type.
40    pub responses: Vec<ResponseSample>,
41}
42
43#[derive(Debug, Clone, PartialEq, serde::Serialize)]
44#[serde(rename_all = "camelCase")]
45pub struct ParamSample {
46    pub name: String,
47    pub location: ParamIn,
48    pub required: bool,
49    pub value: Value,
50}
51
52#[derive(Debug, Clone, PartialEq, serde::Serialize)]
53#[serde(rename_all = "camelCase")]
54pub struct BodySample {
55    pub media_type: String,
56    pub required: bool,
57    pub value: Value,
58}
59
60#[derive(Debug, Clone, PartialEq, serde::Serialize)]
61#[serde(rename_all = "camelCase")]
62pub struct ResponseSample {
63    /// `200`, `4XX` or `default`.
64    pub status: String,
65    pub media_type: String,
66    pub value: Value,
67}
68
69/// The samples of `model`, with warnings where a value could not follow the definition.
70pub fn samples(model: &Model) -> (Samples, Vec<Warning>) {
71    let mut s = Sampler {
72        decls: model.schemas.iter().map(|d| (d.id, d)).collect(),
73        stack: Vec::new(),
74        warnings: Vec::new(),
75        cuts: 0,
76    };
77    let types = model
78        .schemas
79        .iter()
80        .filter_map(|d| s.named(d.id).map(|v| (d.id, v)))
81        .collect();
82    let operations = model.operations.iter().map(|op| s.operation(op)).collect();
83    let mut warnings = s.warnings;
84    warnings.sort();
85    warnings.dedup();
86    (Samples { types, operations }, warnings)
87}
88
89struct Sampler<'a> {
90    decls: HashMap<NameId, &'a TypeDecl>,
91    /// The declarations being sampled, outermost first.
92    stack: Vec<NameId>,
93    warnings: Vec<Warning>,
94    /// How many required cycles were cut with `{}`. Optional properties and array items whose sample
95    /// needed a cut are left out instead (and the cut's warning taken back).
96    cuts: usize,
97}
98
99/// What a value is sampled for: the documentation (examples, defaults, constraints), a name to derive
100/// strings from, and the location (for derived values and warnings).
101#[derive(Clone, Copy)]
102struct At<'a> {
103    doc: Option<&'a Doc>,
104    hint: &'a str,
105    loc: &'a Loc,
106}
107
108impl<'a> At<'a> {
109    fn tag(&self, name: &str) -> Option<&'a Value> {
110        self.doc?
111            .tags
112            .iter()
113            .find(|(n, _)| n == name)
114            .map(|(_, v)| v)
115    }
116
117    fn number(&self, name: &str) -> Option<f64> {
118        self.tag(name).and_then(Value::as_f64)
119    }
120
121    fn size(&self, name: &str) -> Option<usize> {
122        self.tag(name)
123            .and_then(Value::as_u64)
124            .map(|n| n.min(64) as usize)
125    }
126}
127
128/// Why sampling produced nothing.
129enum Missing {
130    /// The type has no value (`never`, `undefined`).
131    None,
132    /// A reference would enter a declaration more than `MAX_DEPTH` times.
133    Cycle,
134}
135
136type Sampled = Result<Value, Missing>;
137
138impl<'a> Sampler<'a> {
139    fn warn(&mut self, kind: WarningKind, loc: &Loc, message: String) {
140        self.warnings.push(Warning {
141            kind,
142            loc: loc.clone(),
143            message,
144            language: None,
145        });
146    }
147
148    fn named(&mut self, id: NameId) -> Option<Value> {
149        self.reference(id).ok()
150    }
151
152    fn reference(&mut self, id: NameId) -> Sampled {
153        let Some(decl) = self.decls.get(&id).copied() else {
154            return Ok(json!({}));
155        };
156        if self.stack.iter().filter(|s| **s == id).count() >= MAX_DEPTH {
157            return Err(Missing::Cycle);
158        }
159        self.stack.push(id);
160        let at = At {
161            doc: decl.doc.as_ref(),
162            hint: "",
163            loc: &decl.loc,
164        };
165        let v = self.sample(&decl.ty, at);
166        self.stack.pop();
167        v
168    }
169
170    fn operation(&mut self, op: &Operation) -> OperationSamples {
171        let loc = &op.loc;
172        let params = op
173            .params
174            .iter()
175            .filter_map(|p| {
176                let ploc = loc.join("parameters").join(&p.name);
177                let at = At {
178                    doc: p.doc.as_ref(),
179                    hint: &p.name,
180                    loc: &ploc,
181                };
182                let value = self.sample(&p.ty, at).ok()?;
183                Some(ParamSample {
184                    name: p.name.clone(),
185                    location: p.location,
186                    required: p.required,
187                    value,
188                })
189            })
190            .collect();
191        let body = op.body.as_ref().and_then(|b| {
192            b.contents.iter().find_map(|c| {
193                let value = self.content(c, b.doc.as_ref(), &loc.join("requestBody"))?;
194                Some(BodySample {
195                    media_type: c.media_type.clone(),
196                    required: b.required,
197                    value,
198                })
199            })
200        });
201        let mut responses = Vec::new();
202        for r in &op.responses {
203            let status = r.status.key();
204            for c in &r.contents {
205                let rloc = loc.join("responses").join(&status);
206                if let Some(value) = self.content(c, None, &rloc) {
207                    responses.push(ResponseSample {
208                        status: status.clone(),
209                        media_type: c.media_type.clone(),
210                        value,
211                    });
212                }
213            }
214        }
215        OperationSamples {
216            operation_id: op.id.clone(),
217            params,
218            body,
219            responses,
220        }
221    }
222
223    /// The body of one media type. Streams have no single value.
224    fn content(&mut self, c: &MediaContent, doc: Option<&Doc>, loc: &Loc) -> Option<Value> {
225        if c.body_kind == BodyKind::Stream || c.body_kind == BodyKind::None {
226            return None;
227        }
228        let at = At { doc, hint: "", loc };
229        self.sample(&c.ty, at).ok()
230    }
231
232    fn sample(&mut self, ty: &Type, at: At<'_>) -> Sampled {
233        // 1. An example, then a default, when it fits the type.
234        for key in ["example", "default"] {
235            if let Some(v) = at.tag(key) {
236                if self.fits(ty, v, 0) {
237                    return Ok(v.clone());
238                }
239            }
240        }
241        // 2. Values from the type.
242        Ok(match ty {
243            Type::Unknown | Type::External(_) => json!({}),
244            Type::Never | Type::Undefined | Type::Ref(_) | Type::Builtin(_) => {
245                return Err(Missing::None);
246            }
247            Type::Null => Value::Null,
248            Type::Boolean => Value::Bool(true),
249            Type::String => self.string(None, at),
250            Type::Number => number(at, false),
251            Type::Binary => Value::String("binary".into()),
252            Type::Scalar(s) => match s.kind {
253                ScalarKind::Integer => number(at, true),
254                ScalarKind::Number => number(at, false),
255                ScalarKind::String => {
256                    let format = s
257                        .format
258                        .as_deref()
259                        .or_else(|| at.tag("format").and_then(Value::as_str));
260                    self.string(format, at)
261                }
262            },
263            Type::Mapped(m) => return self.sample(&m.schema, at),
264            Type::Inline(i) => {
265                let inner = At { loc: &i.loc, ..at };
266                return self.sample(&i.ty, inner);
267            }
268            Type::Enum(e) => match e.values.first() {
269                Some(l) => literal(l),
270                None => Value::Null,
271            },
272            Type::Literal(l) => literal(l),
273            Type::Named(r) => return self.reference(r.id),
274            Type::Array(item) => {
275                let max = at.size("maxItems");
276                if max == Some(0) {
277                    return Ok(json!([]));
278                }
279                let min = at.size("minItems").unwrap_or(0);
280                let item_at = At {
281                    doc: None,
282                    hint: at.hint,
283                    loc: at.loc,
284                };
285                let (cuts, warned) = (self.cuts, self.warnings.len());
286                let sampled = self.sample(item, item_at);
287                if min == 0 && self.cuts > cuts {
288                    self.cuts = cuts;
289                    self.warnings.truncate(warned);
290                    return Ok(json!([]));
291                }
292                match sampled {
293                    Ok(v) => Value::Array(vec![v; min.max(1)]),
294                    Err(_) if min == 0 => json!([]),
295                    Err(e) => return Err(e),
296                }
297            }
298            Type::Tuple(t) => {
299                let mut items = Vec::new();
300                for (i, item) in t.items.iter().take(t.required).enumerate() {
301                    let loc = at.loc.join("prefixItems").join(&i.to_string());
302                    let item_at = At {
303                        doc: None,
304                        hint: at.hint,
305                        loc: &loc,
306                    };
307                    items.push(self.sample(item, item_at)?);
308                }
309                // `minItems` beyond the prefix: rest items.
310                let min = at.size("minItems").unwrap_or(0);
311                if items.len() < min {
312                    let Some(rest) = &t.rest else {
313                        return Err(Missing::None);
314                    };
315                    let rest_at = At {
316                        doc: None,
317                        hint: at.hint,
318                        loc: at.loc,
319                    };
320                    let v = self.sample(rest, rest_at)?;
321                    items.resize(min, v);
322                }
323                Value::Array(items)
324            }
325            Type::Union(ts) => return self.first(ts, at),
326            Type::Choice(c) => {
327                if let Some(d) = &c.discriminator {
328                    for (i, m) in c.members.iter().enumerate() {
329                        let Some(tag) = d.values.get(i).and_then(|v| v.first()) else {
330                            continue;
331                        };
332                        let mut v = self.sample(m, at)?;
333                        let tag = Value::String(tag.clone());
334                        // A member whose own property does not allow the tag (a definition whose
335                        // implicit mapping disagrees with an enum) keeps its own value.
336                        let allowed = self
337                            .property_type(m, &d.property, 0)
338                            .is_none_or(|t| self.fits(t, &tag, 0));
339                        if let (Value::Object(o), true) = (&mut v, allowed) {
340                            o.insert(d.property.clone(), tag);
341                        }
342                        return Ok(v);
343                    }
344                }
345                return self.first(&c.members, at);
346            }
347            Type::Intersection(ts) => {
348                // Objects merge; an object and a value of another JSON type have no common value.
349                // Arrays whose samples differ meet in the empty array.
350                let mut merged = None::<Map<String, Value>>;
351                let mut others: Vec<Value> = Vec::new();
352                for t in ts.iter().filter(|t| **t != Type::Unknown) {
353                    match self.sample(t, at)? {
354                        Value::Object(o) => merged.get_or_insert_with(Map::new).extend(o),
355                        v => others.push(v),
356                    }
357                }
358                // A member whose additional properties do not allow a property of another member
359                // (`additionalProperties: false`, or another type) leaves it out.
360                if let Some(o) = &mut merged {
361                    for t in ts {
362                        let Some(obj) = self.object_of(t, 0) else {
363                            continue;
364                        };
365                        let Some(index) = &obj.index else {
366                            continue;
367                        };
368                        o.retain(|k, v| {
369                            obj.properties.iter().any(|p| p.name == *k) || self.fits(index, v, 0)
370                        });
371                    }
372                }
373                match (merged, others.first()) {
374                    (Some(_), Some(_)) => return Err(Missing::None),
375                    (Some(o), None) => Value::Object(o),
376                    (None, None) => json!({}),
377                    (None, Some(first)) if others.iter().all(|v| v == first) => first.clone(),
378                    (None, Some(_)) if others.iter().all(Value::is_array) => json!([]),
379                    (None, Some(_)) => return Err(Missing::None),
380                }
381            }
382            Type::Tag(t) => match t.values.first() {
383                Some(v) => json!({ t.property.clone(): v }),
384                None => json!({}),
385            },
386            Type::Object(o) => {
387                let mut out = Map::new();
388                for p in &o.properties {
389                    let loc = at.loc.join("properties").join(&p.name);
390                    let p_at = At {
391                        doc: p.doc.as_ref(),
392                        hint: &p.name,
393                        loc: &loc,
394                    };
395                    let (cuts, warned) = (self.cuts, self.warnings.len());
396                    let sampled = self.sample(&p.ty, p_at);
397                    if p.optional && self.cuts > cuts {
398                        self.cuts = cuts;
399                        self.warnings.truncate(warned);
400                        continue;
401                    }
402                    match sampled {
403                        // A flattened `allOf` can keep `additionalProperties` of one member that the
404                        // properties of another do not satisfy; such optional properties are left out.
405                        Ok(v)
406                            if p.optional
407                                && o.index.as_ref().is_some_and(|ix| !self.fits(ix, &v, 0)) => {}
408                        Ok(v) => {
409                            out.insert(p.name.clone(), v);
410                        }
411                        Err(_) if p.optional => {}
412                        Err(Missing::Cycle) => {
413                            self.cuts += 1;
414                            self.warn(
415                                WarningKind::SampleCycle,
416                                &loc,
417                                format!(
418                                    "`{}` is required and refers back to itself; its sample stops at depth {MAX_DEPTH} with `{{}}`",
419                                    p.name
420                                ),
421                            );
422                            out.insert(p.name.clone(), json!({}));
423                        }
424                        Err(e) => return Err(e),
425                    }
426                }
427                Value::Object(out)
428            }
429        })
430    }
431
432    /// The first member with a value, preferring members that are not `null`.
433    fn first(&mut self, members: &[Type], at: At<'_>) -> Sampled {
434        let mut last = Err(Missing::None);
435        for m in members.iter().filter(|m| **m != Type::Null) {
436            match self.sample(m, at) {
437                Ok(v) => return Ok(v),
438                Err(e) => last = Err(e),
439            }
440        }
441        if members.contains(&Type::Null) {
442            return Ok(Value::Null);
443        }
444        last
445    }
446
447    fn string(&mut self, format: Option<&str>, at: At<'_>) -> Value {
448        let fixed = match format {
449            Some("date-time") => Some("2024-01-01T00:00:00Z".to_owned()),
450            Some("date") => Some("2024-01-01".to_owned()),
451            Some("time") => Some("00:00:00Z".to_owned()),
452            Some("duration") => Some("P1D".to_owned()),
453            Some("uuid") => Some(uuid(&at.loc.pointer)),
454            Some("email" | "idn-email") => Some("user@example.com".to_owned()),
455            Some("uri" | "url" | "iri") => Some("https://example.com/".to_owned()),
456            Some("uri-reference" | "iri-reference") => Some("/".to_owned()),
457            Some("hostname" | "idn-hostname") => Some("example.com".to_owned()),
458            Some("ipv4") => Some("192.0.2.1".to_owned()),
459            Some("ipv6") => Some("2001:db8::1".to_owned()),
460            Some("byte") => Some("AAAA".to_owned()),
461            Some("binary") => Some("binary".to_owned()),
462            _ => None,
463        };
464        if let Some(v) = fixed {
465            return Value::String(v);
466        }
467        if at.tag("pattern").is_some() {
468            self.warn(
469                WarningKind::SamplePattern,
470                at.loc,
471                "the sample cannot follow `pattern`; add an `example` to the schema".into(),
472            );
473        }
474        let mut s: String = if at.hint.is_empty() {
475            "string".into()
476        } else {
477            at.hint.to_owned()
478        };
479        if let Some(min) = at.size("minLength") {
480            while s.chars().count() < min {
481                s.push('x');
482            }
483        }
484        if let Some(max) = at.size("maxLength") {
485            s = s.chars().take(max).collect();
486        }
487        Value::String(s)
488    }
489
490    /// The object type `ty` is, through references and inline types.
491    fn object_of<'t>(&'t self, ty: &'t Type, depth: usize) -> Option<&'t tsurara_sem::ir::Object> {
492        if depth > 4 {
493            return None;
494        }
495        match ty {
496            Type::Object(o) => Some(o),
497            Type::Named(r) => self.object_of(&self.decls.get(&r.id)?.ty, depth + 1),
498            Type::Inline(i) => self.object_of(&i.ty, depth + 1),
499            _ => None,
500        }
501    }
502
503    /// The type of property `name` of an object type, through references and intersections.
504    fn property_type<'t>(&'t self, ty: &'t Type, name: &str, depth: usize) -> Option<&'t Type> {
505        if depth > 4 {
506            return None;
507        }
508        match ty {
509            Type::Object(o) => o.properties.iter().find(|p| p.name == name).map(|p| &p.ty),
510            Type::Named(r) => {
511                let decl = self.decls.get(&r.id)?;
512                self.property_type(&decl.ty, name, depth + 1)
513            }
514            Type::Inline(i) => self.property_type(&i.ty, name, depth + 1),
515            Type::Intersection(ts) => ts
516                .iter()
517                .find_map(|t| self.property_type(t, name, depth + 1)),
518            _ => None,
519        }
520    }
521
522    /// Whether `v` has the shape of `ty`: its JSON type, and enum and literal values. Constraints are
523    /// not checked; an example that breaks them is the definition's own mistake.
524    fn fits(&self, ty: &Type, v: &Value, depth: usize) -> bool {
525        match ty {
526            Type::Unknown | Type::External(_) => true,
527            Type::Never | Type::Undefined | Type::Ref(_) | Type::Builtin(_) => false,
528            Type::Null => v.is_null(),
529            Type::Boolean => v.is_boolean(),
530            Type::String | Type::Binary => v.is_string(),
531            Type::Number => v.is_number(),
532            Type::Scalar(s) => match s.kind {
533                ScalarKind::Integer => v.as_f64().is_some_and(|n| n.fract() == 0.0),
534                ScalarKind::Number => v.is_number(),
535                ScalarKind::String => v.is_string(),
536            },
537            Type::Mapped(m) => self.fits(&m.schema, v, depth),
538            Type::Inline(i) => self.fits(&i.ty, v, depth),
539            Type::Enum(e) => {
540                (e.nullable && v.is_null()) || e.values.iter().any(|l| literal(l) == *v)
541            }
542            Type::Literal(l) => literal(l) == *v,
543            Type::Named(r) => {
544                depth > 4
545                    || self
546                        .decls
547                        .get(&r.id)
548                        .is_none_or(|d| self.fits(&d.ty, v, depth + 1))
549            }
550            Type::Array(item) => match v {
551                Value::Array(items) => {
552                    depth > 6 || items.iter().all(|x| self.fits(item, x, depth + 1))
553                }
554                _ => false,
555            },
556            Type::Tuple(_) => v.is_array(),
557            Type::Union(ts) => ts.iter().any(|t| self.fits(t, v, depth)),
558            Type::Choice(c) => c.members.iter().any(|t| self.fits(t, v, depth)),
559            Type::Intersection(ts) => ts.iter().all(|t| self.fits(t, v, depth)),
560            Type::Tag(_) => v.is_object(),
561            // Every property the value has must fit its type; missing ones are not checked.
562            Type::Object(o) => match v {
563                Value::Object(map) => {
564                    depth > 6
565                        || o.properties.iter().all(|p| {
566                            map.get(&p.name)
567                                .is_none_or(|x| self.fits(&p.ty, x, depth + 1))
568                        })
569                }
570                _ => false,
571            },
572        }
573    }
574}
575
576fn literal(l: &Literal) -> Value {
577    match l {
578        Literal::String(s) => Value::String(s.clone()),
579        Literal::Number(n) => Value::Number(n.clone()),
580        Literal::Boolean(b) => Value::Bool(*b),
581    }
582}
583
584/// 1 for integers and 1.5 for numbers, moved into `minimum`/`maximum` (inclusive or exclusive) and
585/// up to a `multipleOf`.
586fn number(at: At<'_>, integer: bool) -> Value {
587    let mut n: f64 = if integer { 1.0 } else { 1.5 };
588    let step = if integer { 1.0 } else { 0.5 };
589    // OpenAPI 3.0 writes exclusive bounds as booleans next to `minimum` and `maximum`.
590    let exclusive = |name: &str| at.tag(name).and_then(Value::as_bool) == Some(true);
591    if let Some(min) = at.number("minimum") {
592        if exclusive("exclusiveMinimum") {
593            if n <= min {
594                n = min + step;
595            }
596        } else if n < min {
597            n = min;
598        }
599    }
600    if let Some(min) = at.number("exclusiveMinimum") {
601        if n <= min {
602            n = min + step;
603        }
604    }
605    if let Some(max) = at.number("maximum") {
606        if exclusive("exclusiveMaximum") {
607            if n >= max {
608                n = max - step;
609            }
610        } else if n > max {
611            n = max;
612        }
613    }
614    if let Some(max) = at.number("exclusiveMaximum") {
615        if n >= max {
616            n = max - step;
617        }
618    }
619    if let Some(m) = at.number("multipleOf").filter(|m| *m > 0.0) {
620        n = (n / m).ceil() * m;
621    }
622    if integer {
623        n = n.ceil();
624        json!(n as i64)
625    } else {
626        json!(n)
627    }
628}
629
630/// A UUID derived from a JSON Pointer: the low 48 bits of its 64-bit FNV-1a hash as the node.
631fn uuid(pointer: &str) -> String {
632    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
633    for byte in pointer.bytes() {
634        hash ^= u64::from(byte);
635        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
636    }
637    format!("00000000-0000-4000-8000-{:012x}", hash & 0xffff_ffff_ffff)
638}