PtcRunner.Kernel.StrictJSON (PtcRunner v0.15.0)

Bounded, duplicate-rejecting JSON admission for authority boundaries.

Objects are decoded as ordered key-value pairs first, then recursively converted to ordinary maps only when every object key is unique. Decoding and trusted in-memory admission share the same depth, node, UTF-8, finite number, timeout, and heap limits.

Summary

Types

error()

located_error()

Functions

admit(value, opts \\ [])

Admits a trusted in-memory JSON value under the same limits as decode/2.

decode(source, opts \\ [])

Decodes one JSON value under the shared structural admission limits.

decode_classified(source, opts \\ [])

Decodes one JSON value and distinguishes proven invalid input from worker unavailability.

decode_with_locations(source, opts \\ [])

Decodes one JSON value and retains the bounded parent location of a duplicate.

Types

error()

@type error() ::
  :invalid_json
  | :duplicate_json_key
  | {:duplicate_json_key, [binary() | non_neg_integer()]}
  | :json_depth_exceeded
  | :json_node_limit_exceeded

located_error()

@type located_error() ::
  error()
  | {:invalid_json,
     [binary() | non_neg_integer() | {:map_key, non_neg_integer()}],
     :improper_list
     | :invalid_object_key
     | :invalid_utf8
     | :non_finite_float
     | :unsupported_value}

Functions

admit(value, opts \\ [])

@spec admit(
  term(),
  keyword()
) :: {:ok, term()} | {:error, error()}

Admits a trusted in-memory JSON value under the same limits as decode/2.

Structs, non-binary keys, invalid UTF-8, improper lists, and non-finite floats are rejected.

decode(source, opts \\ [])

@spec decode(
  binary(),
  keyword()
) :: {:ok, term()} | {:error, error()}

Decodes one JSON value under the shared structural admission limits.

Options may only narrow :max_depth and :max_nodes.

decode_classified(source, opts \\ [])

@spec decode_classified(
  binary(),
  keyword()
) :: {:ok, term()} | {:invalid, error()} | {:unavailable, atom()}

Decodes one JSON value and distinguishes proven invalid input from worker unavailability.

Ordinary JSON, duplicate-key, depth, and node faults are {:invalid, reason}. Timeout, heap exhaustion, cancellation, and worker failure are {:unavailable, cause}. Dispatcher uses this split for json_object structured output so a malformed provider payload is not a host-validator outage.

decode_with_locations(source, opts \\ [])

@spec decode_with_locations(
  binary(),
  keyword()
) :: {:ok, term()} | {:error, error()}

Decodes one JSON value and retains the bounded parent location of a duplicate.

Location segments are internal evidence. Callers must authorize them against their own closed schema before projecting a public path.