use std::collections::{BTreeMap, BTreeSet};
use crate::descriptor::{self, ArgDecl, FunctionDescriptor, Returns, Unit};
use crate::error::{err, ErrorCode, Result};
use crate::json::{self, jcs_sorted, Value};
use crate::lexical;
use crate::model::Type;
use crate::normalisation::KeyNormalisation;
use crate::schema;
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ClassKey {
Scalar {
ty: Type,
unit: Option<Unit>,
key_normalisation: Option<KeyNormalisation>,
},
Class(String),
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct Steward {
pub namespace: String,
pub process: String,
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct ClassExtent {
pub exists: Option<String>,
pub keys: Option<String>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct ClassDescriptor {
pub keys: BTreeMap<String, ClassKey>,
pub order: Vec<String>,
pub methods: BTreeMap<String, String>,
pub steward: Steward,
pub parent: Option<String>,
pub is_final: bool,
pub open: Vec<String>,
pub maps: Vec<String>,
pub inverse: Vec<String>,
pub lookup: Option<String>,
pub extent: Option<ClassExtent>,
pub implements: Vec<String>,
}
impl ClassDescriptor {
pub fn from_json(bytes: &[u8]) -> Result<ClassDescriptor> {
ClassDescriptor::from_value(&json::parse(bytes)?)
}
pub fn from_value(v: &Value) -> Result<ClassDescriptor> {
json::check_value_depth(v)?;
class_structure(v)?;
class_canonical(v)
}
pub fn to_value(&self) -> Value {
let keys = self
.keys
.iter()
.map(|(name, key)| {
let decl = match key {
ClassKey::Class(c) => Value::Object(vec![("class".into(), Value::String(c.clone()))]),
ClassKey::Scalar { ty, unit, key_normalisation } => {
let mut m = vec![("type".to_string(), Value::String(ty.as_str().into()))];
if let Some(u) = unit {
m.push(("unit".into(), u.to_value()));
}
if let Some(r) = key_normalisation {
m.push(("key_normalisation".into(), Value::String(r.as_str().into())));
}
Value::Object(m)
}
};
(name.clone(), decl)
})
.collect();
let strings = |v: &[String]| Value::Array(v.iter().map(|s| Value::String(s.clone())).collect());
let mut m: Vec<(String, Value)> = vec![
("keys".into(), Value::Object(keys)),
("order".into(), strings(&self.order)),
(
"methods".into(),
Value::Object(self.methods.iter().map(|(k, h)| (k.clone(), Value::String(h.clone()))).collect()),
),
(
"steward".into(),
Value::Object(vec![
("namespace".into(), Value::String(self.steward.namespace.clone())),
("process".into(), Value::String(self.steward.process.clone())),
]),
),
];
if let Some(p) = &self.parent {
m.push(("parent".into(), Value::String(p.clone())));
}
if self.is_final {
m.push(("final".into(), Value::Bool(true)));
}
if !self.open.is_empty() {
m.push(("open".into(), strings(&self.open)));
}
if !self.maps.is_empty() {
m.push(("maps".into(), strings(&self.maps)));
}
if !self.inverse.is_empty() {
m.push(("inverse".into(), strings(&self.inverse)));
}
if let Some(l) = &self.lookup {
m.push(("lookup".into(), Value::String(l.clone())));
}
if let Some(e) = &self.extent {
let mut em = Vec::new();
if let Some(x) = &e.exists {
em.push(("exists".to_string(), Value::String(x.clone())));
}
if let Some(x) = &e.keys {
em.push(("keys".to_string(), Value::String(x.clone())));
}
m.push(("extent".into(), Value::Object(em)));
}
if !self.implements.is_empty() {
m.push(("implements".into(), strings(&self.implements)));
}
Value::Object(m)
}
pub fn canonical(&self) -> Vec<u8> {
self.to_value().to_jcs()
}
pub fn hash(&self) -> String {
crate::crypto::sha256_hex(&self.canonical())
}
}
const MAX_KEYS: usize = 32;
const CLASS_REQUIRED: &[&str] = &["keys", "order", "methods", "steward"];
const CLASS_OPTIONAL: &[&str] = &["parent", "final", "open", "maps", "inverse", "lookup", "extent", "implements"];
fn class_structure(v: &Value) -> Result<()> {
let m = schema::object(v, "$")?;
schema::exact(m, CLASS_REQUIRED, CLASS_OPTIONAL, "$", ErrorCode::Schema)?;
let keys = schema::object(schema::get(m, "keys"), "$.keys")?;
for (k, d) in keys {
let p = format!("$.keys.{k}");
let dm = schema::object(d, &p)?;
if schema::opt(dm, "class").is_some() {
schema::exact(dm, &["class"], &[], &p, ErrorCode::Schema)?;
schema::string(dm, "class", &p)?;
} else {
schema::exact(dm, &["type"], &["unit", "key_normalisation"], &p, ErrorCode::Schema)?;
schema::string(dm, "type", &p)?;
if let Some(u) = schema::opt(dm, "unit") {
descriptor::unit_shape(u, &format!("{p}.unit"))?;
}
if schema::opt(dm, "key_normalisation").is_some() {
schema::string(dm, "key_normalisation", &p)?;
}
}
}
string_array(schema::get(m, "order"), "$.order")?;
let methods = schema::object(schema::get(m, "methods"), "$.methods")?;
for (k, h) in methods {
if !matches!(h, Value::String(_)) {
return err(ErrorCode::Schema, &format!("$.methods.{k}"), "a method is a function hash");
}
}
let st = schema::object(schema::get(m, "steward"), "$.steward")?;
schema::exact(st, &["namespace", "process"], &[], "$.steward", ErrorCode::Schema)?;
schema::string(st, "namespace", "$.steward")?;
schema::string(st, "process", "$.steward")?;
if let Some(p) = schema::opt(m, "parent") {
if !matches!(p, Value::String(_)) {
return err(ErrorCode::Schema, "$.parent", "parent is a class hash");
}
}
if let Some(f) = schema::opt(m, "final") {
if !matches!(f, Value::Bool(true)) {
return err(ErrorCode::Schema, "$.final", "final is true when written");
}
}
for name in ["open", "maps", "inverse", "implements"] {
if let Some(a) = schema::opt(m, name) {
let items = string_array(a, &format!("$.{name}"))?;
if items.is_empty() {
return err(ErrorCode::Schema, &format!("$.{name}"), "an optional member is absent, not empty");
}
}
}
if let Some(l) = schema::opt(m, "lookup") {
if !matches!(l, Value::String(_)) {
return err(ErrorCode::Schema, "$.lookup", "lookup is a method name");
}
}
if let Some(e) = schema::opt(m, "extent") {
let em = schema::object(e, "$.extent")?;
if em.is_empty() {
return err(ErrorCode::Schema, "$.extent", "an optional member is absent, not empty");
}
schema::exact(em, &[], &["exists", "keys"], "$.extent", ErrorCode::Schema)?;
for (k, x) in em {
if !matches!(x, Value::String(_)) {
return err(ErrorCode::Schema, &format!("$.extent.{k}"), "an extent function is a hash");
}
}
}
Ok(())
}
fn string_array<'a>(v: &'a Value, path: &str) -> Result<Vec<&'a str>> {
match v {
Value::Array(items) => items
.iter()
.map(|i| match i {
Value::String(s) => Ok(s.as_str()),
_ => err(ErrorCode::Schema, path, "an array of strings"),
})
.collect(),
_ => err(ErrorCode::Schema, path, "an array of strings"),
}
}
fn ascending_unique(items: &[&str], path: &str) -> Result<()> {
if items.windows(2).any(|w| w[0] >= w[1]) {
return err(ErrorCode::CanonSet, path, "entries are strictly ascending");
}
Ok(())
}
fn https_url(s: &str) -> bool {
s.len() <= 512
&& s.strip_prefix("https://").is_some_and(|rest| !rest.is_empty())
&& s.bytes().all(|c| (0x21..=0x7E).contains(&c))
}
fn uri(s: &str) -> bool {
let Some((scheme, rest)) = s.split_once(':') else { return false };
let mut sb = scheme.bytes();
let scheme_ok = matches!(sb.next(), Some(c) if c.is_ascii_alphabetic())
&& sb.all(|c| c.is_ascii_alphanumeric() || matches!(c, b'+' | b'-' | b'.'));
scheme_ok && !rest.is_empty() && s.len() <= 512 && s.bytes().all(|c| (0x21..=0x7E).contains(&c))
}
fn class_canonical(v: &Value) -> Result<ClassDescriptor> {
let m = schema::object(v, "$")?;
let kobj = schema::object(schema::get(m, "keys"), "$.keys")?;
if kobj.len() > MAX_KEYS {
return err(ErrorCode::CanonLimit, "$.keys", "more than 32 keys");
}
let mut keys = BTreeMap::new();
for (name, d) in jcs_sorted(kobj) {
let p = format!("$.keys.{name}");
lexical::check_arg_name(name, &p)?;
let dm = schema::object(d, &p)?;
let key = if schema::opt(dm, "class").is_some() {
let c = schema::string(dm, "class", &p)?;
lexical::check_function_name(c, &p)?;
ClassKey::Class(c.into())
} else {
let ty = Type::parse(schema::string(dm, "type", &p)?, &format!("{p}.type"))?;
if ty == Type::Blob {
return err(ErrorCode::CanonType, &format!("{p}.type"), "a key is never a blob");
}
let unit = match (ty, schema::opt(dm, "unit")) {
(Type::Number, None) => return err(ErrorCode::CanonUnit, &p, "a number key declares its unit"),
(Type::Number, Some(u)) => Some(descriptor::unit_canonical(u, &[], &format!("{p}.unit"))?),
(_, Some(_)) => return err(ErrorCode::CanonUnit, &format!("{p}.unit"), "only a number key has a unit"),
(_, None) => None,
};
let kn = match (ty == Type::String, schema::opt(dm, "key_normalisation")) {
(true, None) => return err(ErrorCode::ClassMember, &p, "a string key declares key_normalisation"),
(true, Some(Value::String(r))) => match KeyNormalisation::from_name(r) {
Some(rule) => Some(rule),
None => return err(ErrorCode::ClassMember, &p, format!("not a rule of 16.4: {r:?}")),
},
(false, Some(_)) => return err(ErrorCode::ClassMember, &p, "only a string key has key_normalisation"),
_ => None,
};
ClassKey::Scalar { ty, unit, key_normalisation: kn }
};
keys.insert(name.clone(), key);
}
let order: Vec<String> = string_array(schema::get(m, "order"), "$.order")?.iter().map(|s| s.to_string()).collect();
let mut seen = BTreeSet::new();
if order.len() != keys.len() || !order.iter().all(|n| keys.contains_key(n) && seen.insert(n.as_str())) {
return err(ErrorCode::CanonSet, "$.order", "order lists every key exactly once");
}
let mut methods = BTreeMap::new();
for (name, h) in jcs_sorted(schema::object(schema::get(m, "methods"), "$.methods")?) {
let p = format!("$.methods.{name}");
lexical::check_name(name, &p)?;
let Value::String(h) = h else { return err(ErrorCode::Schema, &p, "a method is a function hash") };
lexical::check_hex(h, 64, &p)?;
methods.insert(name.clone(), h.clone());
}
let st = schema::object(schema::get(m, "steward"), "$.steward")?;
let namespace = schema::string(st, "namespace", "$.steward")?;
lexical::check_namespace(namespace, "$.steward.namespace")?;
let process = schema::string(st, "process", "$.steward")?;
if !https_url(process) {
return err(ErrorCode::ClassMember, "$.steward.process", "the change process is an https URL");
}
let steward = Steward { namespace: namespace.into(), process: process.into() };
let parent = match schema::opt(m, "parent") {
Some(Value::String(p)) => {
lexical::check_hex(p, 64, "$.parent")?;
Some(p.clone())
}
_ => None,
};
let is_final = matches!(schema::opt(m, "final"), Some(Value::Bool(true)));
let open: Vec<String> = match schema::opt(m, "open") {
Some(a) => {
let items = string_array(a, "$.open")?;
if !is_final {
return err(ErrorCode::ClassMember, "$.open", "open is only with final");
}
ascending_unique(&items, "$.open")?;
if items.iter().any(|n| !methods.contains_key(*n)) {
return err(ErrorCode::ClassMember, "$.open", "open names methods of the class");
}
items.iter().map(|s| s.to_string()).collect()
}
None => Vec::new(),
};
let maps: Vec<String> = match schema::opt(m, "maps") {
Some(a) => {
let items = string_array(a, "$.maps")?;
ascending_unique(&items, "$.maps")?;
if items.iter().any(|s| !uri(s)) {
return err(ErrorCode::ClassMember, "$.maps", "each map is a URI");
}
items.iter().map(|s| s.to_string()).collect()
}
None => Vec::new(),
};
let inverse: Vec<String> = match schema::opt(m, "inverse") {
Some(a) => {
let items = string_array(a, "$.inverse")?;
ascending_unique(&items, "$.inverse")?;
for attr in &items {
lexical::check_arg_name(attr, "$.inverse")?;
if !methods.contains_key(&format!("by_{attr}")) {
return err(ErrorCode::ClassMember, "$.inverse", format!("no method by_{attr}"));
}
}
items.iter().map(|s| s.to_string()).collect()
}
None => Vec::new(),
};
let lookup = match schema::opt(m, "lookup") {
Some(Value::String(l)) => {
if !methods.contains_key(l) {
return err(ErrorCode::ClassMember, "$.lookup", "lookup names a method of the class");
}
Some(l.clone())
}
_ => None,
};
let extent = match schema::opt(m, "extent") {
Some(e) => {
let em = schema::object(e, "$.extent")?;
let mut out = ClassExtent::default();
for (k, x) in em {
let Value::String(x) = x else { return err(ErrorCode::Schema, "$.extent", "a function hash") };
lexical::check_hex(x, 64, &format!("$.extent.{k}"))?;
match k.as_str() {
"exists" => out.exists = Some(x.clone()),
_ => out.keys = Some(x.clone()),
}
}
Some(out)
}
None => None,
};
let implements: Vec<String> = match schema::opt(m, "implements") {
Some(a) => {
let items = string_array(a, "$.implements")?;
ascending_unique(&items, "$.implements")?;
for h in &items {
lexical::check_hex(h, 64, "$.implements")?;
}
items.iter().map(|s| s.to_string()).collect()
}
None => Vec::new(),
};
Ok(ClassDescriptor {
keys,
order,
methods,
steward,
parent,
is_final,
open,
maps,
inverse,
lookup,
extent,
implements,
})
}
#[derive(Clone, Debug, Default)]
pub struct ClassEnv {
definer: String,
functions: BTreeMap<String, FunctionDescriptor>,
classes: BTreeMap<String, ClassDescriptor>,
}
impl ClassEnv {
pub fn new(definer: &str) -> ClassEnv {
ClassEnv { definer: definer.into(), functions: BTreeMap::new(), classes: BTreeMap::new() }
}
pub fn definer(&self) -> &str {
&self.definer
}
pub fn insert_function(&mut self, d: FunctionDescriptor) {
self.functions.insert(d.hash(), d);
}
pub fn insert_class(&mut self, c: ClassDescriptor) {
self.classes.insert(c.hash(), c);
}
pub fn function(&self, hash: &str) -> Option<&FunctionDescriptor> {
self.functions.get(hash)
}
pub fn class(&self, hash: &str) -> Option<&ClassDescriptor> {
self.classes.get(hash)
}
}
pub fn define_class(name: &str, descriptor_json: &[u8], env: &ClassEnv) -> Result<ClassDescriptor> {
lexical::check_function_name(name, "$.name")?;
let owner = name.rsplit_once('/').map(|(ns, _)| ns).unwrap_or_default();
if owner != env.definer() {
return err(ErrorCode::ClassOwner, "$.name", format!("a namespace defines classes under itself: {name:?}"));
}
let own = ClassDescriptor::from_json(descriptor_json)?;
let parent = match &own.parent {
None => None,
Some(p) => {
let parent = env.class(p).ok_or_else(|| {
crate::error::Error::new(ErrorCode::ClassParent, "$.parent", "the parent class is not known")
})?;
if let Some(k) = own.keys.keys().find(|k| parent.keys.contains_key(*k)) {
return err(ErrorCode::ClassInherit, &format!("$.keys.{k}"), "a parent key is declared again");
}
Some(parent)
}
};
let mut flat = own.clone();
if let Some(parent) = parent {
for (m, h) in &own.methods {
let Some(ph) = parent.methods.get(m) else { continue };
if ph == h {
continue;
}
if parent.is_final && !parent.open.iter().any(|o| o == m) {
return err(ErrorCode::ClassFinal, &format!("$.methods.{m}"), "a final class's method is not open");
}
if let (Some(new), Some(old)) = (env.function(h), env.function(ph)) {
if new.signature != old.signature {
return err(
ErrorCode::ClassOverride,
&format!("$.methods.{m}"),
"an override changes the signature",
);
}
}
}
flat.keys = parent.keys.iter().chain(own.keys.iter()).map(|(k, v)| (k.clone(), v.clone())).collect();
flat.order = parent.order.iter().chain(own.order.iter()).cloned().collect();
flat.methods = parent.methods.iter().chain(own.methods.iter()).map(|(k, v)| (k.clone(), v.clone())).collect();
let mut implements: BTreeSet<String> = parent.implements.iter().cloned().collect();
implements.extend(own.implements.iter().cloned());
flat.implements = implements.into_iter().collect();
}
let flat = ClassDescriptor::from_value(&flat.to_value())?;
for (m, h) in &flat.methods {
let f = env.function(h).ok_or_else(|| {
crate::error::Error::new(
ErrorCode::ClassMethod,
format!("$.methods.{m}"),
"the method's function is not known",
)
})?;
let p = format!("$.methods.{m}");
if flat.lookup.as_deref() == Some(m.as_str()) {
check_lookup(f, name, &p)?;
continue;
}
let n = method_key_count(&flat, parent, m);
check_key_arguments(&flat, f, n, &p, ErrorCode::ClassMethod, true)?;
if m == "same_as" {
match &f.returns_classes {
Some(list) if !list.iter().any(|c| c == name) => {}
_ => return err(ErrorCode::ClassMethod, &p, "same_as returns a key of another class"),
}
}
if let Some(attr) = m.strip_prefix("by_") {
if flat.inverse.iter().any(|a| a == attr) && !returns_key_of(f, name) {
return err(ErrorCode::ClassMethod, &p, "an inverse method returns a key of this class");
}
}
}
if let Some(ext) = &flat.extent {
for h in [&ext.exists, &ext.keys].into_iter().flatten() {
let f = env.function(h).ok_or_else(|| {
crate::error::Error::new(ErrorCode::ClassMember, "$.extent", "the extent function is not known")
})?;
check_key_arguments(&flat, f, flat.order.len(), "$.extent", ErrorCode::ClassMember, false)?;
if Some(h) == ext.exists.as_ref() && f.signature.returns.ty != Type::Boolean {
return err(ErrorCode::ClassMember, "$.extent.exists", "exists returns a boolean");
}
}
}
for c in &flat.implements {
let iface = env.class(c).ok_or_else(|| {
crate::error::Error::new(ErrorCode::ClassInterface, "$.implements", "the interface is not known")
})?;
if !iface.keys.is_empty() {
return err(ErrorCode::ClassInterface, "$.implements", "an interface has no keys");
}
for (m, ih) in &iface.methods {
let p = format!("$.implements.{m}");
let class_h = flat.methods.get(m).ok_or_else(|| {
crate::error::Error::new(ErrorCode::ClassInterface, &p, "the class lacks an interface method")
})?;
let (Some(cf), Some(ifn)) = (env.function(class_h), env.function(ih)) else {
return err(ErrorCode::ClassInterface, &p, "a function is not known");
};
let n = method_key_count(&flat, parent, m);
let rest = remaining_signature(cf, n);
if rest != remaining_signature(ifn, 0) {
return err(ErrorCode::ClassInterface, &p, "the method's signature differs from the interface's");
}
}
}
Ok(flat)
}
fn method_key_count(flat: &ClassDescriptor, parent: Option<&ClassDescriptor>, m: &str) -> usize {
match parent {
Some(p) if p.methods.contains_key(m) => p.order.len(),
_ => flat.order.len(),
}
}
fn remaining_signature(f: &FunctionDescriptor, n: usize) -> (Vec<String>, Vec<(String, ArgDecl)>, Returns) {
let order = f.order.clone().unwrap_or_default();
let rest: Vec<String> = order.iter().skip(n).cloned().collect();
let decls = rest.iter().filter_map(|a| f.signature.args.get(a).map(|d| (a.clone(), d.clone()))).collect();
(rest, decls, f.signature.returns.clone())
}
fn check_key_arguments(
flat: &ClassDescriptor,
f: &FunctionDescriptor,
n: usize,
path: &str,
code: ErrorCode,
normalised: bool,
) -> Result<()> {
let Some(order) = &f.order else {
return err(code, path, "a method's function has an order");
};
if order.len() < n {
return err(code, path, "a method takes the class keys first");
}
for (i, name) in flat.order.iter().take(n).enumerate() {
let key = &flat.keys[name];
if order.get(i) != Some(name) {
return err(code, path, format!("key {name:?} is not the first argument in class order"));
}
let Some(decl) = f.signature.args.get(name) else {
return err(code, path, format!("key {name:?} is not an argument"));
};
let extras = f.arg_extras.get(name).cloned().unwrap_or_default();
let ok = match key {
ClassKey::Class(c) => decl.ty == Type::String && extras.classes.as_deref() == Some(&[c.clone()][..]),
ClassKey::Scalar { ty, unit, key_normalisation } => {
decl.ty == *ty
&& decl.unit == *unit
&& (*ty != Type::String
|| !normalised
|| (extras.classes.is_none()
&& extras.key_normalisation.unwrap_or(KeyNormalisation::NoRule)
== key_normalisation.unwrap_or(KeyNormalisation::NoRule)))
}
};
if !ok {
return err(code, path, format!("key {name:?} does not match the class's declaration"));
}
}
Ok(())
}
fn returns_key_of(f: &FunctionDescriptor, class: &str) -> bool {
f.returns_classes.as_ref().is_some_and(|l| l.iter().any(|c| c == class))
}
fn check_lookup(f: &FunctionDescriptor, class: &str, path: &str) -> Result<()> {
let bad = |why: &str| err(ErrorCode::ClassMember, path, format!("the lookup method {why}"));
if f.signature.args.len() != 1 || f.order.as_deref() != Some(&["label".to_string()][..]) {
return bad("takes exactly one argument, label");
}
let Some(label) = f.signature.args.get("label") else { return bad("takes exactly one argument, label") };
if label.ty != Type::String || label.valid || f.arg_extras.get("label").is_some_and(|e| e.classes.is_some()) {
return bad("takes a string label");
}
if f.signature.returns.ty != Type::String || !returns_key_of(f, class) {
return bad("returns a key of this class");
}
Ok(())
}