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.
- checksums.yaml +4 -4
- data/.release-please-manifest.json +1 -1
- data/CHANGELOG.md +127 -0
- data/README.md +96 -44
- data/ROADMAP.md +1 -1
- data/crates/kobako-runtime/CHANGELOG.md +44 -0
- data/crates/kobako-runtime/README.md +1 -1
- data/crates/kobako-transport/CHANGELOG.md +31 -0
- data/crates/kobako-transport/README.md +43 -0
- data/crates/kobako-wasmtime/CHANGELOG.md +30 -0
- data/crates/kobako-wasmtime/README.md +1 -1
- data/data/kobako.wasm +0 -0
- data/lib/kobako/3.3/kobako.so +0 -0
- data/lib/kobako/3.4/kobako.so +0 -0
- data/lib/kobako/4.0/kobako.so +0 -0
- data/lib/kobako/catalog/extensions.rb +50 -43
- data/lib/kobako/catalog/handles.rb +7 -16
- data/lib/kobako/catalog/services.rb +24 -46
- data/lib/kobako/catalog/snippets.rb +16 -33
- data/lib/kobako/codec/decoder.rb +10 -13
- data/lib/kobako/codec/encoder.rb +7 -7
- data/lib/kobako/codec/error.rb +6 -6
- data/lib/kobako/codec/ext_types.rb +12 -72
- data/lib/kobako/codec/handle_walk.rb +6 -6
- data/lib/kobako/codec/state.rb +4 -56
- data/lib/kobako/codec/utils.rb +4 -4
- data/lib/kobako/codec.rb +11 -21
- data/lib/kobako/context.rb +208 -0
- data/lib/kobako/errors.rb +59 -16
- data/lib/kobako/execution.rb +52 -0
- data/lib/kobako/extension.rb +24 -10
- data/lib/kobako/outcome.rb +71 -128
- data/lib/kobako/payload/arguments.rb +59 -0
- data/lib/kobako/payload.rb +19 -0
- data/lib/kobako/pool.rb +1 -7
- data/lib/kobako/sandbox.rb +51 -191
- data/lib/kobako/sandbox_options.rb +24 -3
- data/lib/kobako/snippet/binary.rb +3 -4
- data/lib/kobako/snippet/source.rb +5 -6
- data/lib/kobako/snippet.rb +2 -2
- data/lib/kobako/transport/call.rb +21 -0
- data/lib/kobako/transport/dispatcher.rb +94 -142
- data/lib/kobako/transport/error.rb +21 -5
- data/lib/kobako/transport/reflection.rb +82 -0
- data/lib/kobako/transport/run.rb +25 -33
- data/lib/kobako/transport/yielder.rb +27 -36
- data/lib/kobako/transport.rb +11 -8
- data/lib/kobako/unresolved.rb +17 -0
- data/lib/kobako/usage.rb +7 -7
- data/lib/kobako/version.rb +1 -1
- data/lib/kobako.rb +1 -0
- data/release-please-config.json +47 -2
- data/sig/kobako/catalog/extensions.rbs +4 -6
- data/sig/kobako/catalog/handles.rbs +0 -2
- data/sig/kobako/catalog/services.rbs +4 -4
- data/sig/kobako/catalog/snippets.rbs +4 -2
- data/sig/kobako/codec/error.rbs +4 -4
- data/sig/kobako/codec/ext_types.rbs +0 -7
- data/sig/kobako/codec/state.rbs +0 -4
- data/sig/kobako/codec.rbs +4 -5
- data/sig/kobako/context.rbs +36 -0
- data/sig/kobako/errors.rbs +27 -6
- data/sig/kobako/execution.rbs +24 -0
- data/sig/kobako/extension.rbs +4 -2
- data/sig/kobako/outcome.rbs +12 -13
- data/sig/kobako/payload/arguments.rbs +26 -0
- data/sig/kobako/payload.rbs +4 -0
- data/sig/kobako/pool.rbs +0 -2
- data/sig/kobako/runtime.rbs +44 -14
- data/sig/kobako/sandbox.rbs +5 -24
- data/sig/kobako/sandbox_options.rbs +9 -2
- data/sig/kobako/snippet/binary.rbs +1 -1
- data/sig/kobako/snippet/source.rbs +1 -1
- data/sig/kobako/transport/call.rbs +21 -0
- data/sig/kobako/transport/dispatcher.rbs +9 -11
- data/sig/kobako/transport/error.rbs +11 -0
- data/sig/kobako/transport/reflection.rbs +15 -0
- data/sig/kobako/transport/run.rbs +1 -1
- data/sig/kobako/transport/yielder.rbs +2 -2
- data/sig/kobako/transport.rbs +8 -2
- data/sig/kobako/unresolved.rbs +4 -0
- metadata +18 -12
- data/lib/kobako/fault.rb +0 -38
- data/lib/kobako/outcome/panic.rb +0 -42
- data/lib/kobako/transport/request.rb +0 -76
- data/lib/kobako/transport/response.rb +0 -83
- data/lib/kobako/transport/yield.rb +0 -94
- data/sig/kobako/fault.rbs +0 -19
- data/sig/kobako/outcome/panic.rbs +0 -34
- data/sig/kobako/transport/request.rbs +0 -29
- data/sig/kobako/transport/response.rbs +0 -33
- 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
|
-
#
|
|
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
|
|
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
|
|
70
|
-
#
|
|
71
|
-
#
|
|
72
|
-
#
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
|
110
|
+
# payload the host's codec could not decode out of a well-framed
|
|
111
|
+
# outcome.
|
|
88
112
|
class SandboxError < Error
|
|
89
|
-
include
|
|
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
|
|
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
|
data/lib/kobako/extension.rb
CHANGED
|
@@ -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
|
|
30
|
+
# idiom routes to) with the source of the bound object, declared by
|
|
31
|
+
# explicit keyword:
|
|
31
32
|
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
#
|
|
35
|
-
#
|
|
36
|
-
#
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
#
|
|
40
|
-
|
|
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
|
data/lib/kobako/outcome.rb
CHANGED
|
@@ -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
|
|
9
|
-
#
|
|
10
|
-
# the
|
|
11
|
-
#
|
|
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
|
-
#
|
|
14
|
-
#
|
|
15
|
-
#
|
|
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
|
-
#
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
67
|
-
#
|
|
68
|
-
#
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
97
|
-
#
|
|
98
|
-
#
|
|
99
|
-
#
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
#
|
|
132
|
-
#
|
|
133
|
-
#
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
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
|
|
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
|
-
#
|
|
151
|
-
|
|
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:
|
|
94
|
+
origin: ORIGIN_SANDBOX,
|
|
158
95
|
klass: "Kobako::Transport::Error",
|
|
159
|
-
|
|
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 =
|
|
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
|