kobako 0.19.0-aarch64-linux → 0.21.0-aarch64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +127 -0
  4. data/README.md +96 -44
  5. data/ROADMAP.md +1 -1
  6. data/crates/kobako-runtime/CHANGELOG.md +44 -0
  7. data/crates/kobako-runtime/README.md +1 -1
  8. data/crates/kobako-transport/CHANGELOG.md +31 -0
  9. data/crates/kobako-transport/README.md +43 -0
  10. data/crates/kobako-wasmtime/CHANGELOG.md +30 -0
  11. data/crates/kobako-wasmtime/README.md +1 -1
  12. data/data/kobako.wasm +0 -0
  13. data/lib/kobako/3.3/kobako.so +0 -0
  14. data/lib/kobako/3.4/kobako.so +0 -0
  15. data/lib/kobako/4.0/kobako.so +0 -0
  16. data/lib/kobako/catalog/extensions.rb +50 -43
  17. data/lib/kobako/catalog/handles.rb +7 -16
  18. data/lib/kobako/catalog/services.rb +24 -46
  19. data/lib/kobako/catalog/snippets.rb +16 -33
  20. data/lib/kobako/codec/decoder.rb +10 -13
  21. data/lib/kobako/codec/encoder.rb +7 -7
  22. data/lib/kobako/codec/error.rb +6 -6
  23. data/lib/kobako/codec/ext_types.rb +12 -72
  24. data/lib/kobako/codec/handle_walk.rb +6 -6
  25. data/lib/kobako/codec/state.rb +4 -56
  26. data/lib/kobako/codec/utils.rb +4 -4
  27. data/lib/kobako/codec.rb +11 -21
  28. data/lib/kobako/context.rb +208 -0
  29. data/lib/kobako/errors.rb +59 -16
  30. data/lib/kobako/execution.rb +52 -0
  31. data/lib/kobako/extension.rb +24 -10
  32. data/lib/kobako/outcome.rb +71 -128
  33. data/lib/kobako/payload/arguments.rb +59 -0
  34. data/lib/kobako/payload.rb +19 -0
  35. data/lib/kobako/pool.rb +1 -7
  36. data/lib/kobako/sandbox.rb +51 -191
  37. data/lib/kobako/sandbox_options.rb +24 -3
  38. data/lib/kobako/snippet/binary.rb +3 -4
  39. data/lib/kobako/snippet/source.rb +5 -6
  40. data/lib/kobako/snippet.rb +2 -2
  41. data/lib/kobako/transport/call.rb +21 -0
  42. data/lib/kobako/transport/dispatcher.rb +94 -142
  43. data/lib/kobako/transport/error.rb +21 -5
  44. data/lib/kobako/transport/reflection.rb +82 -0
  45. data/lib/kobako/transport/run.rb +25 -33
  46. data/lib/kobako/transport/yielder.rb +27 -36
  47. data/lib/kobako/transport.rb +11 -8
  48. data/lib/kobako/unresolved.rb +17 -0
  49. data/lib/kobako/usage.rb +7 -7
  50. data/lib/kobako/version.rb +1 -1
  51. data/lib/kobako.rb +1 -0
  52. data/release-please-config.json +47 -2
  53. data/sig/kobako/catalog/extensions.rbs +4 -6
  54. data/sig/kobako/catalog/handles.rbs +0 -2
  55. data/sig/kobako/catalog/services.rbs +4 -4
  56. data/sig/kobako/catalog/snippets.rbs +4 -2
  57. data/sig/kobako/codec/error.rbs +4 -4
  58. data/sig/kobako/codec/ext_types.rbs +0 -7
  59. data/sig/kobako/codec/state.rbs +0 -4
  60. data/sig/kobako/codec.rbs +4 -5
  61. data/sig/kobako/context.rbs +36 -0
  62. data/sig/kobako/errors.rbs +27 -6
  63. data/sig/kobako/execution.rbs +24 -0
  64. data/sig/kobako/extension.rbs +4 -2
  65. data/sig/kobako/outcome.rbs +12 -13
  66. data/sig/kobako/payload/arguments.rbs +26 -0
  67. data/sig/kobako/payload.rbs +4 -0
  68. data/sig/kobako/pool.rbs +0 -2
  69. data/sig/kobako/runtime.rbs +44 -14
  70. data/sig/kobako/sandbox.rbs +5 -24
  71. data/sig/kobako/sandbox_options.rbs +9 -2
  72. data/sig/kobako/snippet/binary.rbs +1 -1
  73. data/sig/kobako/snippet/source.rbs +1 -1
  74. data/sig/kobako/transport/call.rbs +21 -0
  75. data/sig/kobako/transport/dispatcher.rbs +9 -11
  76. data/sig/kobako/transport/error.rbs +11 -0
  77. data/sig/kobako/transport/reflection.rbs +15 -0
  78. data/sig/kobako/transport/run.rbs +1 -1
  79. data/sig/kobako/transport/yielder.rbs +2 -2
  80. data/sig/kobako/transport.rbs +8 -2
  81. data/sig/kobako/unresolved.rbs +4 -0
  82. metadata +18 -12
  83. data/lib/kobako/fault.rb +0 -38
  84. data/lib/kobako/outcome/panic.rb +0 -42
  85. data/lib/kobako/transport/request.rb +0 -76
  86. data/lib/kobako/transport/response.rb +0 -83
  87. data/lib/kobako/transport/yield.rb +0 -94
  88. data/sig/kobako/fault.rbs +0 -19
  89. data/sig/kobako/outcome/panic.rbs +0 -34
  90. data/sig/kobako/transport/request.rbs +0 -29
  91. data/sig/kobako/transport/response.rbs +0 -33
  92. data/sig/kobako/transport/yield.rbs +0 -34
data/lib/kobako/errors.rb CHANGED
@@ -16,10 +16,28 @@ module Kobako
16
16
  # taxonomy can rescue a single class.
17
17
  class Error < StandardError; end
18
18
 
19
+ # Carries the frozen +Kobako::Execution+ of the run that failed, so a
20
+ # rescue reads its captures and usage exactly as a successful caller reads
21
+ # them off the return value. Mixed only into the three invocation-outcome
22
+ # classes (+TrapError+ / +SandboxError+ / +ServiceError+ and their
23
+ # subclasses); +SetupError+ and +PoolTimeoutError+ arise outside any
24
+ # invocation and carry no Execution. Defaults to +nil+ — a pre-flight
25
+ # failure that ran no invocation leaves it unset.
26
+ module CarriesExecution
27
+ attr_reader :execution
28
+
29
+ # Attach the failed run's +Kobako::Execution+ and return +self+ so the
30
+ # raise site reads +raise error.with_execution(execution)+.
31
+ def with_execution(execution)
32
+ @execution = execution
33
+ self
34
+ end
35
+ end
36
+
19
37
  # Wasm engine layer. Raised when the Wasm execution engine crashed
20
38
  # (trap, OOM, unreachable) or when the wire layer detected a structural
21
- # violation that signals a corrupted guest execution environment
22
- # (zero-length OUTCOME_BUFFER, unknown outcome tag).
39
+ # violation that signals a corrupted guest execution environment (an
40
+ # outcome the core envelope cannot frame, an absent one included).
23
41
  #
24
42
  # Two named subclasses cover the configured per-invocation caps:
25
43
  #
@@ -31,7 +49,9 @@ module Kobako
31
49
  # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
32
50
  # want to surface a specific reason to operators can rescue the subclass
33
51
  # first.
34
- class TrapError < Error; end
52
+ class TrapError < Error
53
+ include CarriesExecution
54
+ end
35
55
 
36
56
  # Wall-clock timeout cap exhausted: the absolute deadline
37
57
  # +entry_time + timeout+ passed and the next guest wasm safepoint
@@ -65,35 +85,41 @@ module Kobako
65
85
  class ModuleNotBuiltError < SetupError; end
66
86
 
67
87
  # The structured attribution the two invocation-failure classes carry
68
- # from a decoded guest exception — its +origin+, original +klass+,
69
- # +backtrace_lines+, and +details+ — so a Host App can inspect a failure
70
- # beyond its message. Mixed into both rather than promoted to a shared
71
- # superclass because +SandboxError+ and +ServiceError+ sit in distinct
72
- # branches of the invocation-outcome taxonomy under +Kobako::Error+.
73
- module StructuredError
74
- attr_reader :origin, :klass, :backtrace_lines, :details
75
-
76
- def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
88
+ # from a decoded guest exception — its +origin+, original +klass+, and
89
+ # +backtrace_lines+ — so a Host App can inspect a failure beyond its
90
+ # message. Mixed into both rather than promoted to a shared superclass
91
+ # because +SandboxError+ and +ServiceError+ sit in distinct branches of
92
+ # the invocation-outcome taxonomy under +Kobako::Error+.
93
+ #
94
+ # Data specific to one kind of failure rides a named reader on the
95
+ # subclass that failure raises, the way Ruby pairs NameError#name with
96
+ # +NameError#local_variables+ — see UndefinedEntrypointError.
97
+ module Diagnosable
98
+ attr_reader :origin, :klass, :backtrace_lines
99
+
100
+ def initialize(message, origin: nil, klass: nil, backtrace_lines: nil)
77
101
  super(message)
78
102
  @origin = origin
79
103
  @klass = klass
80
104
  @backtrace_lines = backtrace_lines
81
- @details = details
82
105
  end
83
106
  end
84
107
 
85
108
  # Sandbox / wire layer. Raised when the guest ran to completion but
86
109
  # execution failed due to a mruby script error, a protocol fault, or a
87
- # host-side wire decode failure on an otherwise valid outcome tag.
110
+ # payload the host's codec could not decode out of a well-framed
111
+ # outcome.
88
112
  class SandboxError < Error
89
- include StructuredError
113
+ include Diagnosable
114
+ include CarriesExecution
90
115
  end
91
116
 
92
117
  # Service layer. Raised when a Service capability call inside a mruby
93
118
  # script reported an application-level failure that the script did not
94
119
  # rescue.
95
120
  class ServiceError < Error
96
- include StructuredError
121
+ include Diagnosable
122
+ include CarriesExecution
97
123
  end
98
124
 
99
125
  # HandleExhaustedError is the canonical SandboxError subclass for the
@@ -113,6 +139,23 @@ module Kobako
113
139
  # can +rescue Kobako::BytecodeError+ directly.
114
140
  class BytecodeError < SandboxError; end
115
141
 
142
+ # UndefinedEntrypointError is the SandboxError subclass raised when a
143
+ # +#run+ target names no top-level constant in the guest. It carries the
144
+ # +#name+ that was asked for and the +#available+ names it could have
145
+ # been — the top-level constants the preloaded snippets contributed — so
146
+ # a caller corrects the name from the error rather than by reading the
147
+ # guest source. Ruby pairs NameError#name with
148
+ # +NameError#local_variables+ for the same reason.
149
+ class UndefinedEntrypointError < SandboxError
150
+ attr_reader :name, :available
151
+
152
+ def initialize(message, name: nil, available: [], **)
153
+ super(message, **)
154
+ @name = name
155
+ @available = available
156
+ end
157
+ end
158
+
116
159
  # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
117
160
  # wait exceeded the configured +checkout_timeout+ while every slot was
118
161
  # held. No Sandbox state is touched — retrying succeeds as soon as a holder
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "capture"
4
+ require_relative "usage"
5
+
6
+ module Kobako
7
+ # Kobako::Execution — the frozen result of one +Sandbox#eval+ / +#run+: the
8
+ # decoded +#value+ plus the run's output captures and +#usage+. A successful
9
+ # run returns it; a failed run raises an error carrying the same frozen
10
+ # Execution on the error's +#execution+, so a rescue reads the captures and
11
+ # usage exactly as a successful caller reads them off the return value. On a
12
+ # failed run +#value+ is +nil+ — only the captures and usage are meaningful.
13
+ #
14
+ # +#failed?+ tells the returned Execution from the carried one even when both
15
+ # +#value+ are +nil+ (a run whose last expression was +nil+ versus a failed
16
+ # one). It holds no reference to the raising error, so the error carries the
17
+ # Execution but not the reverse.
18
+ class Execution
19
+ # The deserialized guest value the run produced; +nil+ on a failed run.
20
+ attr_reader :value
21
+
22
+ # The +Kobako::Usage+ resource accounting for this run.
23
+ attr_reader :usage
24
+
25
+ def initialize(value:, usage:, stdout:, stderr:, failed:)
26
+ @value = value
27
+ @usage = usage
28
+ @stdout_capture = stdout
29
+ @stderr_capture = stderr
30
+ @failed = failed
31
+ freeze
32
+ end
33
+
34
+ # Returns +true+ iff the run failed — +false+ on the Execution +#eval+ /
35
+ # +#run+ returned, +true+ on the one a raised error carries.
36
+ def failed? = @failed
37
+
38
+ # Bytes the guest wrote to stdout during this run as a UTF-8 String,
39
+ # clipped at +stdout_limit+; the content carries no truncation sentinel,
40
+ # so use +#stdout_truncated?+ to observe overflow.
41
+ def stdout = @stdout_capture.bytes
42
+
43
+ # Bytes the guest wrote to stderr during this run. Mirror of #stdout.
44
+ def stderr = @stderr_capture.bytes
45
+
46
+ # Returns +true+ iff stdout capture reached +stdout_limit+ during this run.
47
+ def stdout_truncated? = @stdout_capture.truncated?
48
+
49
+ # Returns +true+ iff stderr capture reached +stderr_limit+ during this run.
50
+ def stderr_truncated? = @stderr_capture.truncated?
51
+ end
52
+ end
@@ -27,17 +27,31 @@ module Kobako
27
27
  # Kobako::Extension::Backend — the host attachment of an Extension,
28
28
  # pairing +path+ (the constant path the backend binds at, single-segment
29
29
  # +"File"+ or nested +"MyApp::Store"+, spelling the guest constant the
30
- # idiom routes to) with +provider+ (the source of the bound object).
30
+ # idiom routes to) with the source of the bound object, declared by
31
+ # explicit keyword:
31
32
  #
32
- # A +provider+ that is not itself callable is the bound object, resolved
33
- # once for the Sandbox's life; a callable provider is invoked once per
34
- # invocation to yield that invocation's object, so a fresh object backs
35
- # the path every invocation. Callability is the sole discriminator — a
36
- # fixed backend that is itself callable is supplied through a
37
- # non-callable wrapper. A callable provider that raises propagates its
38
- # exception to the invocation caller and leaves the guest unrun; the
39
- # next invocation resolves it afresh.
40
- class Backend < Data.define(:path, :provider)
33
+ # * +object:+ — a static object, fixed for the Sandbox's life.
34
+ # * +provider:+ — a no-argument callable invoked once per invocation to
35
+ # yield that invocation's object, so a fresh object backs the path
36
+ # every invocation. A provider that raises propagates its exception to
37
+ # the invocation caller and leaves the guest unrun; the next
38
+ # invocation resolves it afresh.
39
+ # * neither — a fillable, defaulting to +Kobako::Unresolved+ until the
40
+ # host supplies the invocation's object.
41
+ #
42
+ # The kind is chosen by keyword, never inferred from whether the value is
43
+ # callable, so a static object that is itself callable is expressed
44
+ # directly with +object:+. Giving both +object:+ and +provider:+ raises
45
+ # +ArgumentError+.
46
+ class Backend < Data.define(:path, :object, :provider)
47
+ def initialize(path:, object: nil, provider: nil)
48
+ if !object.nil? && !provider.nil?
49
+ raise ArgumentError,
50
+ "Extension::Backend accepts object: or provider:, not both"
51
+ end
52
+
53
+ super
54
+ end
41
55
  end
42
56
 
43
57
  # +backend+ and +depends_on+ default to absent so the common
@@ -1,163 +1,106 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "codec"
4
- require_relative "outcome/panic"
5
4
  require_relative "transport/error"
6
5
 
7
6
  module Kobako
8
- # Host-facing boundary for the OUTCOME_BUFFER produced by
9
- # +__kobako_eval+. Takes raw outcome bytes — a one-byte tag followed by
10
- # the msgpack-encoded body — and maps them to either the unwrapped
11
- # mruby return value or a raised three-layer exception.
7
+ # Host-facing boundary for the invocation outcome the native side split
8
+ # off the core envelope. Takes the arm it named plus the fields that arm
9
+ # carries, and settles the invocation the way a host does: return the
10
+ # value, or raise the exception the failure attributes to.
12
11
  #
13
- # Self-contained: this module owns the wire framing (tag bytes,
14
- # body decoding), and the +Panic+ wire record lives at
15
- # +Kobako::Outcome::Panic+. The byte-level msgpack codec at
16
- # +Kobako::Codec+ is invoked for the body itself; otherwise
17
- # nothing in +Transport+ participates.
12
+ # This is the two-step attribution decision. The wire framing belongs to
13
+ # the native side; the payload codec at +Kobako::Codec+ decodes only
14
+ # the one arm that carries a value.
18
15
  module Outcome
19
- # First byte of the OUTCOME_BUFFER for the success branch — body is
20
- # the bare msgpack encoding of the returned value
21
- # ({docs/wire-contract.md Outcome Envelope}[link:../../docs/wire-contract.md]).
22
- TYPE_VALUE = 0x01
23
- # First byte of the OUTCOME_BUFFER for the failure branch — body is
24
- # the msgpack Panic map.
25
- TYPE_PANIC = 0x02
16
+ # The two +origin+ values a Panic attributes with.
17
+ ORIGIN_SANDBOX = "sandbox"
18
+ ORIGIN_SERVICE = "service"
19
+
20
+ # The guest-written class names that select a +SandboxError+ subclass.
21
+ # A name absent here settles as plain +SandboxError+, so the guest
22
+ # widens the taxonomy only by naming a class the host already defines.
23
+ SUBCLASSES = {
24
+ "Kobako::BytecodeError" => BytecodeError,
25
+ "Kobako::UndefinedEntrypointError" => UndefinedEntrypointError
26
+ }.freeze
26
27
 
27
28
  module_function
28
29
 
29
- def decode(bytes)
30
- tag, body = split_tag(bytes)
31
- case tag
32
- when TYPE_VALUE
33
- decode_value(body)
34
- when TYPE_PANIC
35
- decode_panic(body)
36
- else
37
- raise build_trap_error(tag)
38
- end
39
- end
30
+ # Settle one invocation. +kind+ names the arm, +payload+ is the
31
+ # codec-encoded value the +:ok+ arm carries, and +panic+ carries
32
+ # the Panic's fields +[origin, class, message, backtrace, available]+ —
33
+ # present on the panic arm and absent on every other, which is what
34
+ # tells the failure that has a record to attribute from apart from the
35
+ # two that do not. +entrypoint+ is the name this invocation asked for,
36
+ # which the host knows and the wire therefore never carries.
37
+ def reify(kind, payload, panic, entrypoint: nil)
38
+ return decode_value(payload) if kind == :ok
40
39
 
41
- # TrapError for unknown or absent tag
42
- # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
43
- # zero-length output and unrecognised first byte both walk the trap
44
- # path). The absent-vs-present distinction selects the message;
45
- # the raw byte is not actionable to a caller and is not surfaced.
46
- def build_trap_error(tag)
47
- if tag.nil?
48
- TrapError.new("Sandbox exited without producing a result")
49
- else
50
- TrapError.new(
51
- "Sandbox produced an unrecognised result; the runtime is corrupted, " \
52
- "discard this Sandbox before another invocation"
53
- )
54
- end
40
+ raise panic ? panic_error(panic, entrypoint) : trap_error(kind)
55
41
  end
56
42
 
57
- def split_tag(bytes)
58
- bytes = bytes.b
59
- return [nil, "".b] if bytes.empty?
43
+ # Map a Panic's fields onto the three-layer taxonomy. The fields land
44
+ # on the exception verbatim — it carries the record rather than a
45
+ # translation of one.
46
+ def panic_error(panic, entrypoint)
47
+ origin, klass, message, backtrace, available = panic
48
+ selected = error_class(origin, klass)
49
+ attribution = { origin: origin, klass: klass, backtrace_lines: backtrace }
50
+ return selected.new(message, **attribution) unless selected == UndefinedEntrypointError
60
51
 
61
- tag = bytes.getbyte(0) # : Integer
62
- body = bytes.byteslice(1, bytes.bytesize - 1) # : String
63
- [tag, body]
52
+ UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
64
53
  end
65
54
 
66
- # Decode failure on the success tag is a SandboxError: the
67
- # framing was fine, but the carried value is unrepresentable. The
68
- # specific codec fault is stashed in +details+ rather
69
- # than spliced into the message — callers cannot act on the inner
70
- # "Symbol payload must be …" wording, but operators triaging a
71
- # corrupted Sandbox runtime still need it.
72
- def decode_value(body)
73
- # The Result envelope is a payload position: an ext 0x02 Fault in it
74
- # is a wire violation routed into the invalid-result rescue below.
75
- Kobako::Codec.forbid_faults { Kobako::Codec::Decoder.decode(body) }
76
- rescue Kobako::Codec::Error => e
77
- raise build_transport_error(
78
- "Sandbox produced an invalid result value",
79
- detail: e.message
80
- )
81
- end
55
+ # +origin == "service"+ selects ServiceError; a sandbox-origin failure
56
+ # naming one of the guest-written subclass names selects that subclass
57
+ # so callers can rescue that path specifically.
58
+ def error_class(origin, klass)
59
+ return ServiceError if origin == ORIGIN_SERVICE
82
60
 
83
- # Decode failure on the panic tag is a SandboxError. Either
84
- # path raises — on success the decoded Panic is mapped to its three-
85
- # layer exception via +build_panic_error+ and raised; on wire-decode
86
- # failure the rescue path raises the wire-violation +SandboxError+.
87
- def decode_panic(body)
88
- raise build_panic_error(build_panic_record(body))
89
- rescue Kobako::Codec::Error => e
90
- raise build_transport_error(
91
- "Sandbox produced an invalid panic record",
92
- detail: e.message
93
- )
61
+ SUBCLASSES.fetch(klass, SandboxError)
94
62
  end
95
63
 
96
- # Build a +Panic+ value object from the msgpack-decoded body. Raises
97
- # +Kobako::Codec::InvalidType+ when the body is not a map or when
98
- # required keys are missing — both routed by +decode_panic+ to
99
- # +build_transport_error+. The decode runs in block form so
100
- # +Panic.new+'s +ArgumentError+ invariants surface as +InvalidType+
101
- # through the decoder boundary; the message itself is never user-
102
- # facing — it lands in +details+ via the rescue chain above.
103
- def build_panic_record(body)
104
- # The Panic envelope is a payload position: an ext 0x02 Fault in its
105
- # +details+ is a wire violation routed into the invalid-panic rescue.
106
- Kobako::Codec.forbid_faults do
107
- Kobako::Codec::Decoder.decode(body) do |map|
108
- raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
109
-
110
- Panic.new(
111
- origin: map["origin"], klass: map["class"], message: map["message"],
112
- backtrace: map["backtrace"] || [], details: map["details"]
113
- )
114
- end
115
- end
116
- end
64
+ # An arm the host cannot settle: the guest wrote nothing, or wrote
65
+ # bytes the envelope cannot frame. Either leaves nothing to attribute
66
+ # to, so both walk the trap path; only the absent-versus-present
67
+ # distinction selects the message.
68
+ def trap_error(kind)
69
+ return TrapError.new("Sandbox exited without producing a result") if kind == :absent
117
70
 
118
- # Map a decoded Panic record into the corresponding three-layer
119
- # Ruby exception. +origin == "service"+ → ServiceError; everything
120
- # else → SandboxError.
121
- def build_panic_error(panic)
122
- panic_target_class(panic).new(
123
- panic.message,
124
- origin: panic.origin,
125
- klass: panic.klass,
126
- backtrace_lines: panic.backtrace,
127
- details: panic.details
71
+ TrapError.new(
72
+ "Sandbox produced an unrecognised result; the runtime is corrupted, " \
73
+ "discard this Sandbox before another invocation"
128
74
  )
129
75
  end
130
76
 
131
- # Map the panic +class+ field to the matching Ruby exception subclass
132
- # so callers can rescue specific failure paths. +origin="service"+ →
133
- # +ServiceError+; +origin="sandbox"+ plus
134
- # +class="Kobako::BytecodeError"+ selects the +BytecodeError+
135
- # subclass. Everything else falls back to the base class for the
136
- # origin.
137
- def panic_target_class(panic)
138
- case panic.origin
139
- when Panic::ORIGIN_SERVICE
140
- ServiceError
141
- else
142
- panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
143
- end
77
+ # The ok arm's value — the one position a payload codec still
78
+ # owns on this path. A decode fault means the framing was fine but the
79
+ # carried value is unrepresentable.
80
+ def decode_value(payload)
81
+ Kobako::Codec::Decoder.decode(payload)
82
+ rescue Kobako::Codec::Error => e
83
+ raise wire_error("Sandbox produced an invalid result value", diagnostic: e.message)
144
84
  end
145
85
 
146
- # Lift the wire-violation fallback to the real
86
+ # Lift a wire violation the host detected to the real
147
87
  # +Kobako::Transport::Error+ class so callers can +rescue+ it
148
88
  # specifically instead of pattern-matching on +error.klass+. The
149
- # +klass+ field is still populated so existing operator-side
150
- # tooling that greps on the string continues to work.
151
- # +detail+ carries the inner codec / framing message, stashed
152
- # directly into +details+ for operator diagnosis without polluting
153
- # the user-facing +#message+.
154
- def build_transport_error(message, detail: nil)
89
+ # +klass+ field is still populated so existing operator-side tooling
90
+ # that greps on the string continues to work.
91
+ def wire_error(message, diagnostic: nil)
155
92
  Kobako::Transport::Error.new(
156
93
  message,
157
- origin: Panic::ORIGIN_SANDBOX,
94
+ origin: ORIGIN_SANDBOX,
158
95
  klass: "Kobako::Transport::Error",
159
- details: detail
96
+ diagnostic: diagnostic
160
97
  )
161
98
  end
99
+
100
+ # +reify+ is the whole seam: one call settles one invocation, matching
101
+ # the single entry point the Rust frontend's twin exposes. Everything
102
+ # else here is how that decision is reached.
103
+ private_class_method :panic_error, :error_class, :trap_error, :decode_value, :wire_error
104
+ private_constant :ORIGIN_SANDBOX, :ORIGIN_SERVICE, :SUBCLASSES
162
105
  end
163
106
  end
@@ -0,0 +1,59 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../codec"
4
+
5
+ module Kobako
6
+ module Payload
7
+ # The invocation arguments a Call or a Run carries: a 2-element
8
+ # msgpack array, +args+ then +kwargs+. Both elements are always
9
+ # present, so field positions stay stable when either is empty.
10
+ #
11
+ # The positional-versus-keyword split lives here rather than in the
12
+ # core envelope because it is Ruby's call semantics, not the wire's.
13
+ # SPEC pins +kwargs+ keys to Symbols; the invariant is enforced at
14
+ # construction so the value object is the single source of truth.
15
+ #
16
+ # Built on the +class X < Data.define(...)+ subclass form so the class
17
+ # body is fully Steep-visible; see +.rubocop.yml+ for the
18
+ # rationale.
19
+ class Arguments < Data.define(:args, :kwargs)
20
+ def initialize(args: [], kwargs: {})
21
+ raise ArgumentError, "payload args must be Array" unless args.is_a?(Array)
22
+
23
+ validate_kwargs!(kwargs)
24
+ super
25
+ end
26
+
27
+ # Encode to the +[args, kwargs]+ msgpack bytes. The value object's
28
+ # own invariants are the contract; this does not re-check the shape.
29
+ def encode
30
+ Codec::Encoder.encode([args, kwargs])
31
+ end
32
+
33
+ # Decode +bytes+ into an Arguments. Raises +Codec::InvalidTypeError+ when
34
+ # the payload is not the expected 2-element msgpack array, or when the
35
+ # construction invariants reject the decoded fields.
36
+ def self.decode(bytes)
37
+ Codec::Decoder.decode(bytes) do |frame|
38
+ unless frame.is_a?(Array) && frame.length == 2
39
+ raise Codec::InvalidTypeError,
40
+ "an invocation payload is malformed (expected a 2-element array)"
41
+ end
42
+
43
+ args, kwargs = frame
44
+ new(args: args, kwargs: kwargs)
45
+ end
46
+ end
47
+
48
+ private
49
+
50
+ def validate_kwargs!(kwargs)
51
+ raise ArgumentError, "payload kwargs must be Hash" unless kwargs.is_a?(Hash)
52
+
53
+ kwargs.each_key do |key|
54
+ raise ArgumentError, "payload kwargs keys must be Symbol, got #{key.class}" unless key.is_a?(Symbol)
55
+ end
56
+ end
57
+ end
58
+ end
59
+ end
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "payload/arguments"
4
+
5
+ module Kobako
6
+ # The payload shapes that ride inside a core envelope's opaque payload
7
+ # field. The envelope routes a message and the native side decodes it;
8
+ # this layer decides what the resolved method receives, and the byte-level
9
+ # encoding of that shape belongs to +Kobako::Codec+ beneath it.
10
+ #
11
+ # Keeping the two apart is what lets an endpoint with its own schema
12
+ # replace this layer and keep the envelope, so nothing here may reach for
13
+ # a routing field.
14
+ #
15
+ # +Kobako::Payload::Arguments+ is the wire-symmetric peer of
16
+ # +kobako_codec::payload::Arguments+.
17
+ module Payload
18
+ end
19
+ end
data/lib/kobako/pool.rb CHANGED
@@ -47,7 +47,7 @@ module Kobako
47
47
  # discarded and its slot refills by a fresh construction on next
48
48
  # demand.
49
49
  def with
50
- sandbox = checkout
50
+ sandbox = acquire
51
51
  begin
52
52
  yield sandbox
53
53
  rescue TrapError
@@ -61,12 +61,6 @@ module Kobako
61
61
 
62
62
  private
63
63
 
64
- # Acquire a Sandbox and hand it over in pre-invocation state — empty
65
- # output buffers and truncation predicates false.
66
- def checkout
67
- acquire.tap(&:reset_invocation_state!)
68
- end
69
-
70
64
  # The idle-first claim loop: an idle Sandbox wins, unclaimed
71
65
  # capacity constructs, and a full pool waits for a checkin.
72
66
  def acquire