Report over-cap parser input as a structured :input_too_large error

Author: kipcole9

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 * `Localize.LanguageTag.best_match/3` now prefers a territory's own language when candidates are otherwise equidistant, so `sgs` (Samogitian, spoken in Lithuania) matches `lt` rather than `en-LT`. The distance trie scores every candidate sharing the desired script and territory identically, which previously left the winner to depend on the order of the supported list.
 
+* `Localize.ParseError` reports an over-cap input as `reason: :input_too_large` with the byte counts in new `:size` and `:limit` fields, instead of interpolating them into a prose `:reason` string that its own type never allowed. The message, number and unit-identifier parsers all use it, and the oversized input is no longer retained on the exception.
+
 ## [1.0.0] — July 31st, 2026
 
 The first stable release. MF2 message validation is separated from parsing: `Localize.Message.Parser.parse/1` checks syntax, `Localize.Message.Validator.validate/1` checks the TR35 data-model rules, and everything that formats or serializes a message runs both. A message like `.local $count = {$count :number}` — a declaration that reads the variable it declares, which is a Duplicate Declaration error rather than a valid annotation of an external variable — is now rejected wherever it appears rather than only when formatted. The construct for annotating an external variable is `.input {$count :number}`.

lib/localize/exception/parse_error.ex

@@ -20,17 +20,24 @@ defmodule Localize.ParseError do
   `:cause` carries an underlying exception when a higher-level parser
   has wrapped a lower-level one.
 
+  When `:reason` is `:input_too_large` the parse was refused before it
+  began because the input exceeded a configured byte cap. `:size` and
+  `:limit` carry the byte counts and `:detail` names what was being
+  parsed. `:input` is `nil` in this case — retaining the oversized
+  string is the thing the cap exists to prevent.
+
   """
 
   @behaviour Localize.Exception
 
-  defexception [:input, :reason, :offset, :line, :column, :rest, :detail, :cause]
+  defexception [:input, :reason, :offset, :line, :column, :rest, :detail, :cause, :size, :limit]
 
   @type reason ::
           :unexpected_trailing_input
           | :unexpected_input
           | :incomplete_input
           | :invalid_message_format
+          | :input_too_large
 
   @type t :: %__MODULE__{
           input: String.t() | nil,
@@ -40,7 +47,9 @@ defmodule Localize.ParseError do
           column: pos_integer() | nil,
           rest: String.t() | nil,
           detail: String.t() | nil,
-          cause: Exception.t() | nil
+          cause: Exception.t() | nil,
+          size: non_neg_integer() | nil,
+          limit: non_neg_integer() | nil
         }
 
   @impl Localize.Exception
@@ -49,7 +58,8 @@ defmodule Localize.ParseError do
       :unexpected_trailing_input,
       :unexpected_input,
       :incomplete_input,
-      :invalid_message_format
+      :invalid_message_format,
+      :input_too_large
     ]
 
   @impl true
@@ -150,6 +160,20 @@ defmodule Localize.ParseError do
     )
   end
 
+  # The oversized input is deliberately not retained on the struct — it
+  # is the thing we refused to hold. `:size` and `:limit` carry the byte
+  # counts and `:detail` names what was being parsed.
+  def message(%__MODULE__{reason: :input_too_large, size: size, limit: limit, detail: detail})
+      when is_integer(size) and is_integer(limit) do
+    Localize.Exception.safe_message(
+      "message",
+      "The {$detail} is {$size} bytes, which exceeds the configured maximum of {$limit} bytes",
+      detail: detail_or_default(detail, "input"),
+      size: size,
+      limit: limit
+    )
+  end
+
   def message(%__MODULE__{reason: :incomplete_input, input: input}) do
     Localize.Exception.safe_message(
       "message",
@@ -187,6 +211,9 @@ defmodule Localize.ParseError do
   defp detail_or_default(nil), do: ""
   defp detail_or_default(detail) when is_binary(detail), do: detail
 
+  defp detail_or_default(nil, default), do: default
+  defp detail_or_default(detail, _default) when is_binary(detail), do: detail
+
   defp rest_suffix(nil), do: ""
   defp rest_suffix(""), do: ""
   defp rest_suffix(rest) when is_binary(rest), do: " (remaining: #{inspect(rest)})"

lib/localize/message/parser/parser.ex

@@ -34,8 +34,10 @@ defmodule Localize.Message.Parser do
     if byte_size(input) > cap do
       {:error,
        Localize.ParseError.exception(
-         input: "<#{byte_size(input)}-byte message>",
-         reason: "message exceeds the configured maximum of #{cap} bytes"
+         reason: :input_too_large,
+         detail: "message",
+         size: byte_size(input),
+         limit: cap
        )}
     else
       do_parse(input)

lib/localize/number/parser.ex

@@ -110,8 +110,10 @@ defmodule Localize.Number.Parser do
     if byte_size(string) > cap do
       {:error,
        Localize.ParseError.exception(
-         input: "<#{byte_size(string)}-byte number>",
-         reason: "number string exceeds the configured maximum of #{cap} bytes"
+         reason: :input_too_large,
+         detail: "number string",
+         size: byte_size(string),
+         limit: cap
        )}
     else
       do_parse(string, options)

lib/localize/unit/parser.ex

@@ -41,8 +41,10 @@ defmodule Localize.Unit.Parser do
       byte_size(input) > cap ->
         {:error,
          Localize.ParseError.exception(
-           input: "<#{byte_size(input)}-byte unit identifier>",
-           reason: "unit identifier exceeds the configured maximum of #{cap} bytes"
+           reason: :input_too_large,
+           detail: "unit identifier",
+           size: byte_size(input),
+           limit: cap
          )}
 
       custom_unit_name?(input) ->