Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c
SHA-256: 85ebfc0c7f53cf4e7952f9ec440395646d48d9100ad2ea191d9c053759625a65
-module(tmux_schema). -moduledoc """ Validate schema-defined observations and normalize scalar values. Field names come from the generated registry, never record reflection or payload-created atoms. Text is validated UTF-8; byte fields preserve arbitrary binaries. Integer normalization uses the shared exact JSON integer range. `m:tmux_model` validates rows and `m:tmux_filter` validates criteria through this schema. The [field reference](fields.md) lists fields and relationships. """. -export([fields/1, relations/1, field/2, normalize/2, value/2, operators/1]). -export_type([entity/0, error_detail/0, value_type/0, field_metadata/0, relation_metadata/0, operator/0]). -doc """ The built-in tmux graph entities; window_link represents a session membership. """. -type entity() :: session | window | window_link | pane. -doc """ Structured boundary validation errors with a code and input path. """. -type error_detail() :: #{code := atom(), path := [term()], atom() => term()}. -doc "Scalar categories used by normalization and operator validation; IDs remain binaries.". -type value_type() :: session_id | window_id | pane_id | boolean | uint | integer | text | bytes. -doc """ Generated field contract. stable is a versioned portable identity; wire is the JSON key. required controls construction and nullable permits known absence. format is present only for directly observed tmux fields; derived fields omit it. capture_codec identifies an admitted batched source encoding; its absence selects isolated reads for that entity. minimum tightens an integer field's lower bound. Field names themselves are the keys returned by `fields/1`, not this map's wire or stable values. """. -type field_metadata() :: #{type := value_type(), wire := binary(), stable := binary(), required := boolean(), nullable := boolean(), format => binary(), capture_codec => escaped_columns_v1, minimum => integer()}. -doc """ Generated relationship contract: kind is one or many; target names the related entity. wire and stable have the same roles as in `t:field_metadata/0`. Completeness belongs to snapshot coverage, not this static schema. """. -type relation_metadata() :: #{kind := one | many, target := entity(), wire := binary(), stable := binary()}. -doc "Validated scalar operators. The field's type and nullability restrict this set.". -type operator() :: equals | 'not' | in | not_in | lt | lte | gt | gte | contains | starts_with | ends_with | regex | present. -define(MAX_INTEGER, 9007199254740991). -doc """ Return generated field metadata for a known entity, or a tagged unknown_entity error. Field names, wire names and stable IDs are allowlisted; this is not reflection over arbitrary record fields. """. -spec fields(entity()) -> {ok, #{atom() => field_metadata()}} | {error, error_detail()}. fields(Entity) -> case lists:member(Entity, tmux_schema_data:entities()) of true -> {ok, tmux_schema_data:fields(Entity)}; false -> {error, #{code => unknown_entity, path => []}} end. -doc """ Return generated relationship metadata, including target entities and one/many cardinality. Performs no I/O. """. -spec relations(entity()) -> {ok, #{atom() => relation_metadata()}} | {error, error_detail()}. relations(Entity) -> maybe {ok, _} ?= fields(Entity), {ok, tmux_schema_data:relations(Entity)} end. -doc """ Look up one permitted field by its Erlang atom name. Unknown names return a tagged error; this does not turn input strings into atoms. """. -spec field(entity(), atom()) -> {ok, field_metadata()} | {error, error_detail()}. field(Entity, Field) -> maybe {ok, Fields} ?= fields(Entity), case maps:find(Field, Fields) of {ok, Metadata} -> {ok, Metadata}; error -> {error, #{code => unknown_field, path => [Field]}} end end. -doc """ Validate a domain-field map and normalize its scalar observations, retaining not_loaded/unavailable distinctly and deriving schema-defined values. Performs no I/O; constructors and action boundaries still validate records. """. -spec normalize(entity(), map()) -> {ok, map()} | {error, error_detail()}. normalize(Entity, Input) when is_map(Input) -> maybe {ok, Fields} ?= fields(Entity), ok ?= known_keys(maps:keys(Input), Fields), {ok, Normalized} ?= observations(lists:sort(maps:to_list(Fields)), Input, #{}), derived(Entity, Normalized) end; normalize(_Entity, _Input) -> {error, #{code => invalid_object, path => []}}. -doc """ Validate and normalize one value against generated field metadata. Integral JSON numbers obey the exact shared integer range and field bounds; text is validated UTF-8, while bytes remain arbitrary binaries. Performs no I/O. """. -spec value(map(), term()) -> {ok, term()} | {error, error_detail()}. value(#{nullable := true}, none) -> {ok, none}; value(#{type := boolean}, Value) when is_boolean(Value) -> {ok, Value}; value(#{type := text} = Metadata, Value) when is_binary(Value) -> case unicode:characters_to_binary(Value, utf8, utf8) of Value -> {ok, Value}; _ -> invalid(Metadata) end; value(#{type := bytes}, Value) when is_binary(Value) -> {ok, Value}; value(#{type := Type} = Metadata, Value) when Type =:= integer; Type =:= uint -> DefaultMinimum = case Type of uint -> 0; integer -> -?MAX_INTEGER end, Minimum = maps:get(minimum, Metadata, DefaultMinimum), case Value of Integer when is_integer(Integer, Minimum, ?MAX_INTEGER) -> {ok, Integer}; Float when is_float(Float), Float >= Minimum, Float =< ?MAX_INTEGER -> Integer = trunc(Float), case Integer == Float of true -> {ok, Integer}; false -> invalid(Metadata) end; _ -> invalid(Metadata) end; value(#{type := Type} = Metadata, Value) when Type =:= pane_id; Type =:= window_id; Type =:= session_id -> Prefix = case Type of pane_id -> $%; window_id -> $@; session_id -> $$ end, case valid_id(Prefix, Value) of true -> {ok, Value}; false -> invalid(Metadata) end; value(Metadata, _Value) -> invalid(Metadata). -doc """ Return the permitted scalar operators for this field type and nullability. The generated field reference uses this same validator. Performs no I/O. """. -spec operators(#{type := value_type(), nullable := boolean(), atom() => term()}) -> [operator()]. operators(#{type := Type, nullable := Nullable}) -> Base = [equals, 'not', in, not_in], Typed = case Type of uint -> [lt, lte, gt, gte]; integer -> [lt, lte, gt, gte]; text -> [contains, starts_with, ends_with, regex]; bytes -> [contains, starts_with, ends_with]; _ -> [] end, Base ++ Typed ++ case Nullable of true -> [present]; false -> [] end. known_keys([], _Fields) -> ok; known_keys([Key | Rest], Fields) -> case maps:is_key(Key, Fields) of true -> known_keys(Rest, Fields); false -> {error, #{code => unknown_field, path => [Key]}} end. observations([], _Input, Accumulator) -> {ok, Accumulator}; observations([{Name, Metadata} | Rest], Input, Accumulator) -> Raw = maps:get(Name, Input, not_loaded), case observation(Metadata, Raw) of {ok, Value} -> observations(Rest, Input, Accumulator#{Name => Value}); {error, Detail} -> {error, Detail#{path => [Name]}} end. observation(#{required := true}, Value) when Value =:= not_loaded; Value =:= unavailable -> {error, #{code => required_field, path => []}}; observation(_Metadata, Value) when Value =:= not_loaded; Value =:= unavailable -> {ok, Value}; observation(Metadata, Value) -> value(Metadata, Value). derived(session, #{attached_count := Count, attached := Attached} = Fields) when is_integer(Count) -> Expected = Count > 0, case Attached of not_loaded -> {ok, Fields#{attached => Expected}}; Expected -> {ok, Fields}; _ -> {error, #{code => inconsistent_derived_value, path => [attached]}} end; derived(_Entity, Fields) -> {ok, Fields}. invalid(#{type := Type}) -> {error, #{code => invalid_value, path => [], expected => Type}}. valid_id(Prefix, <<Prefix, Digits/binary>>) when byte_size(Digits) =< 32 -> case Digits of <<"0">> -> true; <<First, Rest/binary>> when First >= $1, First =< $9 -> digits(Rest); _ -> false end; valid_id(_Prefix, _Value) -> false. digits(<<>>) -> true; digits(<<Digit, Rest/binary>>) when Digit >= $0, Digit =< $9 -> digits(Rest); digits(_) -> false.