console 1.35.1 → 1.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e161d51958a96742a44541c862e32c9354c04d3cdae04cfe57ef0a63b2ecfd36
-  data.tar.gz: 48afe3e18acbc12cd72b96c22a139fd9de69e852c0ba8e98a4367811ca1e916e
+  metadata.gz: 749f01df7fec2a4868a2b4958b23ee328ddb2911b0fc2a635bdf298d901cae60
+  data.tar.gz: 32daa46920a77f0fa713685d0176dc24ed034fe39fe99cde3d1d789ecfb1c48b
 SHA512:
-  metadata.gz: 2caf9a3c2520460b7a54489bf4ed68a9f0f37223a45917500884b8f5a1c531ebb602a1dda943994925c716d9af785c11c07f2263704572db3ed343f9858c75a6
-  data.tar.gz: aaf33117df4b08e942b8975128bb11a11b653580c85dfe93218d5a4af0a16db69385d4907a37d461a3d3e89c6ef6578ecef4aaca3ec07e3d1d63c56c66111283
+  metadata.gz: 51796e3366c0778f6e811428ff9e8aeffb0a34fe99ce0528488fd9931c392596c1a654f34e49781f68afd1377898ef16ce6aeaaa3a35c82c201bf4579f423073
+  data.tar.gz: 82af50570a7e55a26562cda15f7ccf5622bcc956ef6b6a065f4a1e38ecf663911f84ccf6a47de1443bc85f1b1e79effeec1fcbdccc21480c0b18b53872efdc13

data/lib/console/format/safe.rb

@@ -10,31 +10,166 @@ module Console
 	module Format
 		# A safe format for converting objects to strings.
 		# 
-		# Handles issues like circular references and encoding errors.
+		# Handles issues like circular references, encoding errors, excessive nesting depth, and excessive output size.
 		class Safe
+			# The JSON fragment used as the truncation marker when dropped fields cannot be named.
+			TRUNCATED = "\"truncated\":true"
+			
 			# Create a new safe format.
 			#
 			# @parameter format [JSON] The format to use for serialization.
-			# @parameter limit [Integer] The maximum depth to recurse into objects.
+			# @parameter depth_limit [Integer] The maximum depth to recurse into objects (the JSON `max_nesting`).
+			# @parameter size_limit [Integer | Nil] The maximum byte size of the serialized output, or `nil` to disable size limiting. Limits below {TRUNCATED} (the minimal marker) cannot be honoured.
 			# @parameter encoding [Encoding] The encoding to use for strings.
-			def initialize(format: ::JSON, limit: 12, encoding: ::Encoding::UTF_8)
+			# @parameter limit [Integer | Nil] Deprecated alias for `depth_limit`.
+			def initialize(format: ::JSON, depth_limit: 12, size_limit: 16 * 1024, encoding: ::Encoding::UTF_8, limit: nil)
+				if limit
+					warn "Console::Format::Safe `limit:` is deprecated, use `depth_limit:` instead.", uplevel: 1, category: :deprecated
+					depth_limit = limit
+				end
+				
 				@format = format
-				@limit = limit
+				@depth_limit = depth_limit
+				@size_limit = size_limit
 				@encoding = encoding
 			end
 			
+			# @attribute [Integer] The maximum depth to recurse into objects.
+			attr :depth_limit
+			
+			# @attribute [Integer | Nil] The maximum byte size of the serialized output.
+			attr :size_limit
+			
 			# Dump the given object to a string.
 			#
+			# The common case is a single fast serialization. If that fails (e.g. circular
+			# references, excessive nesting, or encoding errors) or its output exceeds
+			# {size_limit}, it falls back to {safe_dump}, which rebuilds the record
+			# field-by-field within the limit.
+			#
 			# @parameter object [Object] The object to dump.
 			# @returns [String] The dumped object.
 			def dump(object)
-				@format.dump(object, @limit)
-			rescue SystemStackError, StandardError => error
-				@format.dump(safe_dump(object, error))
+				buffer = @format.dump(object, @depth_limit)
+				
+				if @size_limit and buffer.bytesize > @size_limit
+					return safe_dump(object)
+				end
+				
+				return buffer
+			rescue SystemStackError, StandardError
+				return safe_dump(object)
 			end
 			
 			private
 			
+			# Produce a safe, size-limited serialization of the given object. This is the
+			# fallback path, used both when direct serialization fails (an exception) and
+			# when its output exceeds {size_limit}.
+			#
+			# Each top-level value is serialized independently and defensively, so a single
+			# un-serializable or oversized value cannot break or bloat the whole record.
+			# Whenever a field is degraded, the reason is recorded in a trailing `"truncated"`
+			# object that maps the field name to why it was truncated:
+			#
+			# - `"key": true` — the value was dropped because it did not fit the size limit.
+			# - `"key": {error}` — the value could not be serialized directly; a safe
+			#   representation was kept in its place and the triggering error is recorded.
+			#
+			# Fields are kept while they fit, always reserving room for at least a minimal
+			# `"truncated":true` marker. The detailed reason map is then emitted only if it
+			# fits in the remaining space; otherwise it degrades to `"truncated":true`. This
+			# is best-effort — in the worst case the per-field detail is lost — but it keeps
+			# the bookkeeping simple and the size guarantee hard.
+			#
+			# @parameter object [Object] The object to serialize.
+			# @returns [String] The safe, size-limited serialized record.
+			def safe_dump(object)
+				# Serialize hash-like objects field-by-field; anything else falls through to the
+				# error handler below, which emits a minimal truncated marker.
+				object = object.to_hash
+				
+				# Serialize each field once, capturing the error for any value that could not be
+				# serialized directly. Our own "truncated" key is skipped so it is never duplicated.
+				errors = {}
+				fragments = []
+				object.each do |key, value|
+					name = key.to_s
+					next if name == "truncated"
+					
+					fragment, error = dump_pair(key, value)
+					errors[name] = error_info(error) if error
+					fragments << [name, fragment]
+				end
+				
+				# Assemble the body, keeping each field while it fits — always reserving room for
+				# at least a minimal `"truncated":true` marker. Each truncated field's reason is
+				# collected: its error (value recovered) or `true` (dropped for size).
+				buffer = +"{"
+				first = true
+				reasons = {}
+				
+				fragments.each do |name, fragment|
+					if buffer.bytesize + (first ? 0 : 1) + fragment.bytesize + TRUNCATED.bytesize + 2 <= @size_limit
+						buffer << "," unless first
+						buffer << fragment
+						first = false
+						
+						# The value was kept; if it had to be recovered, note why.
+						reasons[name] = errors[name] if errors[name]
+					else
+						# The value did not fit and was dropped entirely.
+						reasons[name] = true
+					end
+				end
+				
+				unless reasons.empty?
+					# Include the detailed reasons if they fit, otherwise fall back to the minimal
+					# marker so the truncation is still signalled.
+					detailed = "\"truncated\":#{@format.dump(reasons)}"
+					fits = buffer.bytesize + (first ? 0 : 1) + detailed.bytesize + 1 <= @size_limit
+					
+					buffer << "," unless first
+					buffer << (fits ? detailed : TRUNCATED)
+				end
+				
+				buffer << "}"
+				
+				return buffer
+			rescue SystemStackError, StandardError
+				return "{#{TRUNCATED}}"
+			end
+			
+			# Serialize a single top-level `"key":value` pair, safely handling values that
+			# cannot be serialized directly.
+			#
+			# @parameter key [Object] The field key.
+			# @parameter value [Object] The field value.
+			# @returns [Array(String, Exception | Nil)] The `"key":value` fragment and the error, if recovery was needed.
+			def dump_pair(key, value)
+				value_json, error = dump_value(value)
+				
+				return ["#{dump_string(String(key))}:#{value_json}", error]
+			end
+			
+			# Serialize a single value, falling back to a safe representation on failure.
+			#
+			# @parameter value [Object] The value to serialize.
+			# @returns [Array(String, Exception | Nil)] The serialized value and the error, if recovery was needed.
+			def dump_value(value)
+				[@format.dump(value, @depth_limit), nil]
+			rescue SystemStackError, StandardError => error
+				[@format.dump(safe_dump_recurse(value)), error]
+			end
+			
+			# Serialize a string as a JSON string, encoding it safely first.
+			#
+			# @parameter value [String] The string to serialize.
+			# @returns [String] The serialized (quoted) string.
+			def dump_string(value)
+				@format.dump(value.encode(@encoding, invalid: :replace, undef: :replace))
+			end
+			
 			# Filter the backtrace to remove duplicate frames and reduce verbosity.
 			#
 			# @parameter error [Exception] The exception to filter.
@@ -76,24 +211,16 @@ module Console
 				return frames
 			end
 			
-			# Dump the given object to a string, replacing it with a safe representation if there is an error.
-			#
-			# This is a slow path so we try to avoid it.
+			# Build a safe, primitive representation of an error for inclusion as an `"error"` field.
 			#
-			# @parameter object [Object] The object to dump.
 			# @parameter error [Exception] The error that occurred while dumping the object.
-			# @returns [Hash] The dumped (truncated) object including error details.
-			def safe_dump(object, error)
-				object = safe_dump_recurse(object)
-				
-				object[:truncated] = true
-				object[:error] = {
+			# @returns [Hash] The error details (class, message, filtered backtrace).
+			def error_info(error)
+				{
 					class: safe_dump_recurse(error.class.name),
 					message: safe_dump_recurse(error.message),
 					backtrace: safe_dump_recurse(filter_backtrace(error)),
 				}
-				
-				return object
 			end
 			
 			# Create a new hash with identity comparison.
@@ -107,7 +234,7 @@ module Console
 			# @parameter limit [Integer] The maximum depth to recurse into objects.
 			# @parameter objects [Hash] The objects that have already been visited.
 			# @returns [Object] The dumped object as a primitive representation.
-			def safe_dump_recurse(object, limit = @limit, objects = default_objects)
+			def safe_dump_recurse(object, limit = @depth_limit, objects = default_objects)
 				case object
 				when Hash
 					if limit <= 0 || objects[object]

data/lib/console/format.rb

@@ -6,6 +6,7 @@
 require_relative "format/safe"
 
 module Console
+	# @namespace
 	module Format
 		# A safe format for converting objects to strings.
 		#

data/lib/console/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2019-2026, by Samuel Williams.
 
 module Console
-	VERSION = "1.35.1"
+	VERSION = "1.36.0"
 end

data/readme.md

@@ -34,6 +34,12 @@ Please see the [project documentation](https://socketry.github.io/console/) for
 
 Please see the [project releases](https://socketry.github.io/console/releases/index) for all releases.
 
+### v1.36.0
+
+  - Add a `size_limit` to `Console::Format::Safe` (default 16KiB) which rebuilds oversized records field-by-field, keeping as many top-level fields as fit within the limit.
+  - Degraded fields are recorded in a `truncated` object that maps each field name to why it was truncated: `true` (dropped for size) or the error (the value could not be serialized directly and a safe representation was kept in its place).
+  - Rename `Console::Format::Safe`'s `limit:` to `depth_limit:` (with a deprecated `limit:` alias) to clarify its purpose alongside the new `size_limit:`.
+
 ### v1.35.0
 
   - Fix handling of `Errno::ENODEV` errors when calculating the width of a terminal that was been re-opened to `File::NULL`.
@@ -74,12 +80,6 @@ Please see the [project releases](https://socketry.github.io/console/releases/in
 
   - Fix logging `exception:` keyword argument when the value was not an exception.
 
-### v1.29.0
-
-  - Don't make `Kernel#warn` redirection to `Console.warn` the default behavior, you must `require 'console/warn'` to enable it.
-  - Remove deprecated `Console::Logger#failure`.
-  - [Consistent handling of exceptions.](https://socketry.github.io/console/releases/index#consistent-handling-of-exceptions.)
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v1.36.0
+
+  - Add a `size_limit` to `Console::Format::Safe` (default 16KiB) which rebuilds oversized records field-by-field, keeping as many top-level fields as fit within the limit.
+  - Degraded fields are recorded in a `truncated` object that maps each field name to why it was truncated: `true` (dropped for size) or the error (the value could not be serialized directly and a safe representation was kept in its place).
+  - Rename `Console::Format::Safe`'s `limit:` to `depth_limit:` (with a deprecated `limit:` alias) to clarify its purpose alongside the new `size_limit:`.
+
 ## v1.35.0
 
   - Fix handling of `Errno::ENODEV` errors when calculating the width of a terminal that was been re-opened to `File::NULL`.

data.tar.gz.sig

@@ -1,2 +1,2 @@
-S�Ll�<	��|~\@T�ޙ���C����c< ���+xY�2	��jFp  ��ԁ3j0���]B���������Ҡ��mz�ZR�eE�*f/�_g�SoeN��p:���F��j���a,��" �V��1K�C]r?�yj����lU�a��%q9N6�+C��D誃��l܃�p ��a@��1�
-�N���� I�5�e�&�i��k��x���}�� �Քb+�d_>e� 6l�mчw@����C�b"3k(�N��T��:D�p'5�����sJ�^�T��LQ��Z{m�3���^%Ԙ8,"\���r�M(X�v�2l�NڧEӶ�jʹ�Z9�մ��:���L��o���w"��3� hR�~�E�HF�f���S
+:}��CS4��
<\i�&��<ք��P��]�ן��:�C��3�l
����|Q���'���]G
+�[�����

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console
 version: !ruby/object:Gem::Version
-  version: 1.35.1
+  version: 1.36.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -163,7 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Beautiful logging for Ruby.
 test_files: []