kobako 0.14.0-aarch64-linux → 0.15.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 (50) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +51 -0
  4. data/README.md +104 -29
  5. data/ROADMAP.md +2 -3
  6. data/SECURITY.md +1 -1
  7. data/crates/kobako-runtime/CHANGELOG.md +7 -0
  8. data/crates/kobako-runtime/README.md +1 -1
  9. data/crates/kobako-wasmtime/CHANGELOG.md +7 -0
  10. data/crates/kobako-wasmtime/README.md +1 -1
  11. data/data/kobako.wasm +0 -0
  12. data/lib/kobako/3.3/kobako.so +0 -0
  13. data/lib/kobako/3.4/kobako.so +0 -0
  14. data/lib/kobako/4.0/kobako.so +0 -0
  15. data/lib/kobako/catalog/handles.rb +1 -1
  16. data/lib/kobako/catalog/services.rb +123 -0
  17. data/lib/kobako/catalog/snippets.rb +1 -1
  18. data/lib/kobako/catalog.rb +2 -2
  19. data/lib/kobako/codec/decoder.rb +3 -3
  20. data/lib/kobako/codec/encoder.rb +4 -4
  21. data/lib/kobako/codec/ext_types.rb +169 -0
  22. data/lib/kobako/codec/state.rb +98 -0
  23. data/lib/kobako/codec/utils.rb +2 -2
  24. data/lib/kobako/codec.rb +23 -6
  25. data/lib/kobako/fault.rb +1 -1
  26. data/lib/kobako/handle.rb +1 -1
  27. data/lib/kobako/outcome.rb +13 -7
  28. data/lib/kobako/pool.rb +1 -1
  29. data/lib/kobako/sandbox.rb +20 -13
  30. data/lib/kobako/transport/dispatcher.rb +25 -18
  31. data/lib/kobako/transport/request.rb +14 -9
  32. data/lib/kobako/transport/response.rb +9 -2
  33. data/lib/kobako/transport/yield.rb +4 -1
  34. data/lib/kobako/transport/yielder.rb +14 -6
  35. data/lib/kobako/version.rb +1 -1
  36. data/sig/kobako/catalog/services.rbs +25 -0
  37. data/sig/kobako/codec/ext_types.rbs +31 -0
  38. data/sig/kobako/codec/state.rbs +20 -0
  39. data/sig/kobako/codec.rbs +3 -0
  40. data/sig/kobako/sandbox.rbs +1 -1
  41. data/sig/kobako/transport/dispatcher.rbs +4 -4
  42. data/sig/kobako/transport/yielder.rbs +1 -1
  43. data/sig/kobako/transport.rbs +2 -2
  44. metadata +8 -8
  45. data/lib/kobako/catalog/namespaces.rb +0 -115
  46. data/lib/kobako/codec/factory.rb +0 -187
  47. data/lib/kobako/namespace.rb +0 -78
  48. data/sig/kobako/catalog/namespaces.rbs +0 -17
  49. data/sig/kobako/codec/factory.rbs +0 -34
  50. data/sig/kobako/namespace.rbs +0 -21
@@ -70,7 +70,10 @@ module Kobako
70
70
  body = bytes.byteslice(1, bytes.bytesize - 1) # : String
71
71
 
72
72
  reject_dead_tag!(tag)
73
- new(tag: tag, value: Codec::Decoder.decode(body))
73
+ # A YieldResponse is a payload position: an ext 0x02 Fault in its
74
+ # value is a wire violation (the Response fault field is the
75
+ # envelope's only home).
76
+ new(tag: tag, value: Codec.forbid_faults { Codec::Decoder.decode(body) })
74
77
  end
75
78
 
76
79
  def self.reject_dead_tag!(tag)
@@ -52,8 +52,14 @@ module Kobako
52
52
  def yield(*args)
53
53
  raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
54
54
 
55
- response = Kobako::Transport::Yield.decode(@yield_to_guest.call(Kobako::Codec::Encoder.encode(args)))
56
- return restore(response.value) if response.ok?
55
+ # Yield arguments are a payload position: a +Kobako::Fault+ among
56
+ # them has no wire representation, so the encode refuses it at
57
+ # this call site. The tracking bracket below opens only around the
58
+ # decode: the guest re-entry may run nested dispatches whose own
59
+ # brackets would otherwise pollute the signal.
60
+ bytes = @yield_to_guest.call(Kobako::Codec.forbid_faults { Kobako::Codec::Encoder.encode(args) })
61
+ response, carried_handle = Kobako::Codec.track_handles { Kobako::Transport::Yield.decode(bytes) }
62
+ return restore(response.value, carried_handle) if response.ok?
57
63
 
58
64
  throw @break_tag, response.value if response.break?
59
65
 
@@ -78,10 +84,12 @@ module Kobako
78
84
  # Restore any Capability Handle in a block's ok value to its host
79
85
  # object via the injected +Catalog::Handles+. Only the
80
86
  # ok path calls this — host code consumes the ok value, whereas a
81
- # break value returns to the guest and stays a Handle. Walks nested
82
- # Array / Hash one level at a time; a plain value passes through
83
- # unchanged.
84
- def restore(value)
87
+ # break value returns to the guest and stays a Handle. A response
88
+ # whose decode carried no Handle resolves to itself, so the walk is
89
+ # skipped entirely.
90
+ def restore(value, carried_handle)
91
+ return value unless carried_handle
92
+
85
93
  Kobako::Codec::HandleWalk.deep_restore(value, @handler)
86
94
  end
87
95
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Kobako
4
- VERSION = "0.14.0"
4
+ VERSION = "0.15.0"
5
5
  end
@@ -0,0 +1,25 @@
1
+ module Kobako
2
+ module Catalog
3
+ class Services
4
+ NAME_PATTERN: Regexp
5
+
6
+ def initialize: (?handler: Kobako::Catalog::Handles) -> void
7
+
8
+ def bind: (Symbol | String path, untyped object) -> self
9
+
10
+ def lookup: (Symbol | String target) -> untyped
11
+
12
+ def encode: () -> String
13
+
14
+ def seal!: () -> self
15
+
16
+ def sealed?: () -> bool
17
+
18
+ private
19
+
20
+ def validate_path!: (Symbol | String path) -> String
21
+
22
+ def collision?: (String path) -> bool
23
+ end
24
+ end
25
+ end
@@ -0,0 +1,31 @@
1
+ module Kobako
2
+ module Codec
3
+ module ExtTypes
4
+ EXT_SYMBOL: Integer
5
+ EXT_HANDLE: Integer
6
+ EXT_ERRENV: Integer
7
+
8
+ def self?.build_factory: () -> MessagePack::Factory
9
+
10
+ def self?.pack_symbol: (Symbol symbol) -> String
11
+
12
+ def self?.unpack_symbol: (String payload) -> Symbol
13
+
14
+ def self?.pack_handle: (Kobako::Handle handle) -> String
15
+
16
+ def self?.unpack_handle: (String payload, State state) -> Kobako::Handle
17
+
18
+ def self?.pack_fault: (Kobako::Fault fault, State state) -> String
19
+
20
+ def self?.unpack_fault: (String payload, State state) -> Kobako::Fault
21
+
22
+ def self?.register_symbol: (MessagePack::Factory factory) -> void
23
+
24
+ def self?.register_handle: (MessagePack::Factory factory) -> void
25
+
26
+ def self?.register_fault: (MessagePack::Factory factory) -> void
27
+ end
28
+
29
+ FACTORY: MessagePack::Factory
30
+ end
31
+ end
@@ -0,0 +1,20 @@
1
+ module Kobako
2
+ module Codec
3
+ class State
4
+ MAX_EXT_DEPTH: Integer
5
+ STATE_KEY: Symbol
6
+
7
+ def self.current: () -> State
8
+
9
+ def track_handles: [T] { () -> T } -> [T, bool]
10
+ def record_handle!: () -> void
11
+ def forbid_faults: [T] { () -> T } -> T
12
+ def faults_forbidden?: () -> bool
13
+ def within_ext_frame: [T] (singleton(Kobako::Codec::Error) over_limit) { () -> T } -> T
14
+
15
+ private
16
+
17
+ def initialize: () -> void
18
+ end
19
+ end
20
+ end
data/sig/kobako/codec.rbs CHANGED
@@ -1,5 +1,8 @@
1
1
  module Kobako
2
2
  module Codec
3
+ def self.track_handles: [T] { () -> T } -> [T, bool]
4
+ def self.forbid_faults: [T] { () -> T } -> T
5
+
3
6
  # The Handle allocator/resolver a wire walk works against: alloc
4
7
  # registers a non-wire-representable object and returns its Handle,
5
8
  # fetch resolves a wire Handle id back to the live object. The
@@ -29,7 +29,7 @@ module Kobako
29
29
 
30
30
  attr_reader usage: Kobako::Usage
31
31
 
32
- def define: (Symbol | String name) -> Kobako::Namespace
32
+ def bind: (Symbol | String path, untyped object) -> Kobako::Sandbox
33
33
 
34
34
  def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
35
35
  | (binary: String) -> Kobako::Sandbox
@@ -12,9 +12,9 @@ module Kobako
12
12
 
13
13
  CALLABLE_ALLOW: Array[Symbol]
14
14
 
15
- def self?.dispatch: (String request_bytes, Kobako::Transport::_NamespaceRegistry namespaces, Kobako::Codec::_HandleTable handler, Kobako::Transport::_GuestYielder yield_to_guest) -> String
15
+ def self?.dispatch: (String request_bytes, Kobako::Transport::_ServiceRegistry services, Kobako::Codec::_HandleTable handler, Kobako::Transport::_GuestYielder yield_to_guest) -> String
16
16
 
17
- def self?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Codec::_HandleTable handler) -> [Array[untyped], Hash[Symbol, untyped]]
17
+ def self?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Codec::_HandleTable handler, bool carried_handle) -> [Array[untyped], Hash[Symbol, untyped]]
18
18
 
19
19
  def self?.encode_caught_error: (StandardError error) -> String
20
20
 
@@ -26,9 +26,9 @@ module Kobako
26
26
 
27
27
  def self?.resolve_arg: (untyped value, Kobako::Codec::_HandleTable handler) -> untyped
28
28
 
29
- def self?.resolve_target: (String | Kobako::Handle target, Kobako::Transport::_NamespaceRegistry namespaces, Kobako::Codec::_HandleTable handler) -> untyped
29
+ def self?.resolve_target: (String | Kobako::Handle target, Kobako::Transport::_ServiceRegistry services, Kobako::Codec::_HandleTable handler) -> untyped
30
30
 
31
- def self?.resolve_path: (String path, Kobako::Transport::_NamespaceRegistry namespaces) -> untyped
31
+ def self?.resolve_path: (String path, Kobako::Transport::_ServiceRegistry services) -> untyped
32
32
 
33
33
  def self?.require_live_object!: (Integer id, Kobako::Codec::_HandleTable handler) -> untyped
34
34
 
@@ -16,7 +16,7 @@ module Kobako
16
16
 
17
17
  private
18
18
 
19
- def restore: (untyped value) -> untyped
19
+ def restore: (untyped value, bool carried_handle) -> untyped
20
20
 
21
21
  def yield_failure: (untyped payload, default: String) -> RuntimeError
22
22
  end
@@ -10,10 +10,10 @@ module Kobako
10
10
  end
11
11
 
12
12
  # The Service registry a dispatch resolves constant-path targets
13
- # against. The Sandbox's Kobako::Catalog::Namespaces is the
13
+ # against. The Sandbox's Kobako::Catalog::Services is the
14
14
  # production conformer; modelled structurally so the Transport
15
15
  # layer needs no upward dependency on Catalog.
16
- interface _NamespaceRegistry
16
+ interface _ServiceRegistry
17
17
  def lookup: (String target) -> untyped
18
18
  end
19
19
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: kobako
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.14.0
4
+ version: 0.15.0
5
5
  platform: aarch64-linux
6
6
  authors:
7
7
  - Aotokitsuruya
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-07-08 00:00:00.000000000 Z
11
+ date: 2026-07-11 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: msgpack
@@ -51,19 +51,19 @@ files:
51
51
  - lib/kobako/capture.rb
52
52
  - lib/kobako/catalog.rb
53
53
  - lib/kobako/catalog/handles.rb
54
- - lib/kobako/catalog/namespaces.rb
54
+ - lib/kobako/catalog/services.rb
55
55
  - lib/kobako/catalog/snippets.rb
56
56
  - lib/kobako/codec.rb
57
57
  - lib/kobako/codec/decoder.rb
58
58
  - lib/kobako/codec/encoder.rb
59
59
  - lib/kobako/codec/error.rb
60
- - lib/kobako/codec/factory.rb
60
+ - lib/kobako/codec/ext_types.rb
61
61
  - lib/kobako/codec/handle_walk.rb
62
+ - lib/kobako/codec/state.rb
62
63
  - lib/kobako/codec/utils.rb
63
64
  - lib/kobako/errors.rb
64
65
  - lib/kobako/fault.rb
65
66
  - lib/kobako/handle.rb
66
- - lib/kobako/namespace.rb
67
67
  - lib/kobako/outcome.rb
68
68
  - lib/kobako/outcome/panic.rb
69
69
  - lib/kobako/pool.rb
@@ -89,19 +89,19 @@ files:
89
89
  - sig/kobako/capture.rbs
90
90
  - sig/kobako/catalog.rbs
91
91
  - sig/kobako/catalog/handles.rbs
92
- - sig/kobako/catalog/namespaces.rbs
92
+ - sig/kobako/catalog/services.rbs
93
93
  - sig/kobako/catalog/snippets.rbs
94
94
  - sig/kobako/codec.rbs
95
95
  - sig/kobako/codec/decoder.rbs
96
96
  - sig/kobako/codec/encoder.rbs
97
97
  - sig/kobako/codec/error.rbs
98
- - sig/kobako/codec/factory.rbs
98
+ - sig/kobako/codec/ext_types.rbs
99
99
  - sig/kobako/codec/handle_walk.rbs
100
+ - sig/kobako/codec/state.rbs
100
101
  - sig/kobako/codec/utils.rbs
101
102
  - sig/kobako/errors.rbs
102
103
  - sig/kobako/fault.rbs
103
104
  - sig/kobako/handle.rbs
104
- - sig/kobako/namespace.rbs
105
105
  - sig/kobako/outcome.rbs
106
106
  - sig/kobako/outcome/panic.rbs
107
107
  - sig/kobako/pool.rbs
@@ -1,115 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require_relative "handles"
4
- require_relative "../codec"
5
- require_relative "../errors"
6
- require_relative "../namespace"
7
-
8
- module Kobako
9
- module Catalog
10
- # Kobako::Catalog::Namespaces — per-Sandbox registry of
11
- # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
12
- # and the preamble emitted on Frame 1.
13
- #
14
- # Public API:
15
- #
16
- # namespaces = Kobako::Catalog::Namespaces.new
17
- # namespace = namespaces.define(:MyService) # => Kobako::Namespace
18
- # namespace.bind(:KV, kv_object) # => namespace (chainable)
19
- # namespaces.encode # => msgpack bytes for Frame 1
20
- # namespaces.lookup("MyService::KV") # => kv_object
21
- #
22
- # Namespaces live at +Kobako::Namespace+. Per-dispatch routing is
23
- # +Kobako::Transport::Dispatcher+'s responsibility — the Dispatcher
24
- # receives this registry and the +Catalog::Handles+ as arguments from
25
- # the +Runtime#on_dispatch+ Proc that +Kobako::Sandbox#initialize+
26
- # installs. The registry holds an injected +Catalog::Handles+ reference so
27
- # dispatch target resolution and host→guest auto-wrap share the same
28
- # Sandbox-owned allocator.
29
- class Namespaces
30
- # Build a fresh registry. +handler+ is an internal seam that injects
31
- # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
32
- # is pinned near +MAX_ID+ to exercise the cap-exhaustion path
33
- # without 2³¹ allocations. Production callers leave it at the default.
34
- def initialize(handler: Catalog::Handles.new)
35
- @namespaces = {} # : Hash[String, Kobako::Namespace]
36
- @handler = handler
37
- @sealed = false
38
- @encoded = nil # : String?
39
- end
40
-
41
- # Declare or retrieve the Namespace named +name+ (idempotent).
42
- # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
43
- # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
44
- # name, creating it if it does not exist. Raises +ArgumentError+ when
45
- # +name+ is malformed, or when called after the owning Sandbox has been
46
- # sealed by its first invocation.
47
- def define(name)
48
- raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
49
-
50
- name_str = name.to_s
51
- unless Namespace::NAME_PATTERN.match?(name_str)
52
- raise ArgumentError,
53
- "Namespace name must match #{Namespace::NAME_PATTERN.inspect} (got #{name.inspect})"
54
- end
55
-
56
- @namespaces[name_str] ||= Namespace.new(name_str)
57
- end
58
-
59
- # Resolve a +target+ path of the form +"<Namespace>::<Member>"+
60
- # (e.g. +"MyService::KV"+) to the bound Host object. +target+ is a
61
- # two-level path using the +::+ separator. Returns the bound Host
62
- # object. Raises +KeyError+ when the namespace or the member is not
63
- # bound.
64
- def lookup(target)
65
- namespace_name, member_name = target.to_s.split("::", 2)
66
- namespace = @namespaces[namespace_name]
67
- raise KeyError, "no namespace named #{namespace_name.inspect}" if namespace.nil?
68
- raise KeyError, "no member in target #{target.inspect}" unless member_name
69
-
70
- namespace.fetch(member_name)
71
- end
72
-
73
- # Encode the preamble as msgpack bytes for stdin Frame 1 delivery.
74
- # Routes through Kobako::Codec::Encoder like every other host-side
75
- # wire encode so there is a single codec path; the preamble carries
76
- # only Strings and Arrays, so none of the kobako ext types actually
77
- # fire. Structure: +[["Namespace", ["MemberA", "MemberB"]], ...]+.
78
- # Returns a binary +String+ of msgpack bytes.
79
- #
80
- # Once sealed, the bytes are computed once and reused for every
81
- # subsequent invocation: sealing freezes Service registration at the
82
- # first invocation, so the preamble is exactly the bindings that
83
- # existed at that moment — a bind reaching a +Kobako::Namespace+
84
- # after the seal raises +ArgumentError+ and never alters Frame 1.
85
- # The memo is gated on the seal rather than dropped per mutation (the
86
- # +Catalog::Snippets#encode+ approach) because a +Member+ bind lands
87
- # on a child +Kobako::Namespace+, invisible to this collection; only
88
- # the seal guarantees nothing further can change.
89
- def encode
90
- return @encoded if @encoded
91
-
92
- bytes = Codec::Encoder.encode(@namespaces.values.map(&:to_preamble)).freeze
93
- @encoded = bytes if @sealed
94
- bytes
95
- end
96
-
97
- # Mark the registry as sealed and propagate the seal to every
98
- # declared +Kobako::Namespace+. Called by +Sandbox+ on the first
99
- # invocation. After sealing, both #define and +Namespace#bind+
100
- # raise ArgumentError. Idempotent.
101
- def seal!
102
- return self if @sealed
103
-
104
- @sealed = true
105
- @namespaces.each_value(&:seal!)
106
- self
107
- end
108
-
109
- # Returns +true+ when #seal! has been called, +false+ otherwise.
110
- def sealed?
111
- @sealed
112
- end
113
- end
114
- end
115
- end
@@ -1,187 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require "singleton"
4
- require "forwardable"
5
- require "msgpack"
6
-
7
- require_relative "error"
8
- require_relative "utils"
9
- require_relative "../handle"
10
- require_relative "../fault"
11
-
12
- module Kobako
13
- module Codec
14
- # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
15
- # registration ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
16
- # § Ext Types).
17
- #
18
- # The factory is the single place in the host gem that touches the
19
- # msgpack API — both Encoder and Decoder delegate through it, so
20
- # the three kobako ext codes (0x00 Symbol, 0x01 Capability Handle,
21
- # 0x02 Exception envelope) are configured exactly once at first use.
22
- #
23
- # Lifecycle is owned by +Singleton+ from the Ruby standard library:
24
- # +Factory.instance+ is lazy, thread-safe, and process-wide. Class-level
25
- # +Factory.dump+ / +Factory.load+ shortcuts are exposed via
26
- # +SingleForwardable+ so callers do not have to spell the +.instance+
27
- # hop at every call site; the instance-level +#dump+ / +#load+ are in
28
- # turn delegated to the wrapped +MessagePack::Factory+ via +Forwardable+.
29
- class Factory
30
- include Singleton
31
- extend Forwardable
32
- extend SingleForwardable
33
-
34
- # MessagePack ext type code reserved for Symbol
35
- # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
36
- # → ext 0x00). Class-private — mirrors +codec::EXT_SYMBOL+ on the
37
- # Rust side.
38
- EXT_SYMBOL = 0x00
39
- # MessagePack ext type code reserved for Capability Handle
40
- # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
41
- # → ext 0x01). Class-private — mirrors +codec::EXT_HANDLE+ on the
42
- # Rust side.
43
- EXT_HANDLE = 0x01
44
- # MessagePack ext type code reserved for Exception envelope
45
- # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
46
- # → ext 0x02). Class-private — mirrors +codec::EXT_ERRENV+ on the
47
- # Rust side.
48
- EXT_ERRENV = 0x02
49
- private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
50
-
51
- # An ext 0x02 (Fault) envelope nests through its +details+ field, and
52
- # each level re-enters the codec with a fresh +MessagePack+ unpacker
53
- # whose built-in stack guard resets — so ext-envelope depth is tracked
54
- # here instead. The cap matches the wire's overall nesting bound and
55
- # keeps a nested chain from exhausting the native stack: an over-deep
56
- # chain fails as a clean wire error, never a stack-level trap.
57
- MAX_EXT_DEPTH = 128
58
- EXT_DEPTH_KEY = :__kobako_codec_ext_depth__
59
- private_constant :MAX_EXT_DEPTH, :EXT_DEPTH_KEY
60
-
61
- # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
62
- # Spelled +def_instance_delegators+ rather than +def_delegators+ because
63
- # the class also extends +SingleForwardable+ (see the +extend+ block
64
- # above), which defines its own +def_delegators+ that shadows
65
- # +Forwardable+'s — the unambiguous forms keep both delegation tiers
66
- # wired to the right scope.
67
- def_instance_delegators :@factory, :dump, :load
68
-
69
- # Class-level shortcuts so callers can write +Factory.dump(v)+ instead
70
- # of +Factory.instance.dump(v)+; both resolve to the same singleton.
71
- def_single_delegators :instance, :dump, :load
72
-
73
- def initialize
74
- @factory = MessagePack::Factory.new
75
- register_symbol
76
- register_handle
77
- register_fault
78
- end
79
-
80
- private
81
-
82
- def register_symbol
83
- @factory.register_type(
84
- EXT_SYMBOL, Symbol,
85
- packer: method(:pack_symbol),
86
- unpacker: method(:unpack_symbol)
87
- )
88
- end
89
-
90
- # Symbol-to-name packer for the ext-0x00 registration.
91
- def pack_symbol(symbol)
92
- symbol.name
93
- end
94
-
95
- # Validate the ext-0x00 payload as UTF-8 and intern. Raises
96
- # InvalidEncoding on invalid bytes — SPEC forbids the
97
- # binary-encoding fallback that msgpack-gem's default unpacker
98
- # would otherwise apply. The re-tag step lives here because the
99
- # msgpack ext-type unpacker hands us binary bytes; the assertion
100
- # itself is shared with Decoder via Utils.assert_utf8!. The
101
- # +"Symbol"+ label keeps the error message in Ruby vocabulary
102
- # rather than wire-ext-code vocabulary.
103
- def unpack_symbol(payload)
104
- name = payload.b.force_encoding(Encoding::UTF_8)
105
- Utils.assert_utf8!(name, "Symbol payload")
106
- name.to_sym
107
- end
108
-
109
- def register_handle
110
- @factory.register_type(
111
- EXT_HANDLE, Kobako::Handle,
112
- packer: ->(handle) { [handle.id].pack("N") },
113
- unpacker: ->(payload) { unpack_handle(payload) }
114
- )
115
- end
116
-
117
- def register_fault
118
- @factory.register_type(
119
- EXT_ERRENV, Kobako::Fault,
120
- packer: ->(fault) { pack_fault(fault) },
121
- unpacker: ->(payload) { unpack_fault(payload) }
122
- )
123
- end
124
-
125
- # Peel off the fixext-4 frame, hand the bytes to the
126
- # Host-Gem-internal +Kobako::Handle.restore+ factory, and
127
- # translate the +ArgumentError+ raised by Handle's invariants
128
- # into a wire-layer +InvalidType+ via Codec::Utils.with_boundary.
129
- # The Value Object owns the id-range contract; this method only
130
- # owns the frame shape.
131
- def unpack_handle(payload)
132
- bytes = payload.b
133
- raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
134
-
135
- id = bytes.unpack1("N") # : Integer
136
- Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
137
- end
138
-
139
- # Encode the inner ext-0x02 map via Encoder (not +factory.dump+) so
140
- # the embedded payload flows through the same boundary as a top-level
141
- # encode — nested kobako values (Handle, nested Fault) reach the
142
- # registered ext-type packers via the cached singleton. A +details+
143
- # chain nested past MAX_EXT_DEPTH has no wire representation and
144
- # surfaces as +UnsupportedType+.
145
- def pack_fault(fault)
146
- within_ext_frame(UnsupportedType) do
147
- Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
148
- end
149
- end
150
-
151
- # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
152
- # inside Decoder.decode's block form, so the value-object's
153
- # +ArgumentError+ invariants surface as +InvalidType+ through the
154
- # decoder boundary. Inner decode goes through Decoder (not
155
- # +factory.load+) so the embedded +str+ payloads flow through the
156
- # same UTF-8 validation as a top-level decode. A nested ext 0x02 in
157
- # +details+ re-enters this method, so #within_ext_frame bounds the
158
- # chain depth to keep it from exhausting the native stack.
159
- def unpack_fault(payload)
160
- within_ext_frame(InvalidType) do
161
- Decoder.decode(payload) do |map|
162
- raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
163
-
164
- Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
165
- end
166
- end
167
- end
168
-
169
- # Track ext-envelope re-entry depth and refuse a chain past
170
- # MAX_EXT_DEPTH, raising +over_limit+ so the failure lands in the
171
- # caller's existing wire-error class. The counter is thread-scoped and
172
- # balanced by the +ensure+, so a raise mid-chain still unwinds it to
173
- # its entry value.
174
- def within_ext_frame(over_limit)
175
- depth = (Thread.current[EXT_DEPTH_KEY] || 0) + 1
176
- raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
177
-
178
- Thread.current[EXT_DEPTH_KEY] = depth
179
- begin
180
- yield
181
- ensure
182
- Thread.current[EXT_DEPTH_KEY] = depth - 1
183
- end
184
- end
185
- end
186
- end
187
- end
@@ -1,78 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Kobako
4
- # A named grouping of Members for one Sandbox.
5
- # Returned by +Sandbox#define+. Each instance owns a flat name→object
6
- # table of Members; member binding is validated against NAME_PATTERN.
7
- class Namespace
8
- # Ruby constant-name pattern shared by Namespace and Member names.
9
- NAME_PATTERN = /\A[A-Z]\w*\z/
10
-
11
- attr_reader :name
12
-
13
- # Build a new Namespace. +name+ is an already-validated Namespace
14
- # name (must satisfy NAME_PATTERN; validation is the caller's
15
- # responsibility).
16
- def initialize(name)
17
- @name = name
18
- @members = {} # : Hash[String, untyped]
19
- @sealed = false
20
- end
21
-
22
- # Bind +object+ under +member+ inside this Namespace. +member+ is a
23
- # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
24
- # object that responds to the methods guest code will invoke. Returns
25
- # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
26
- # match the constant pattern, when a Member of the same name is
27
- # already bound, or when the owning Sandbox's first invocation has
28
- # sealed Service registration.
29
- def bind(member, object)
30
- raise ArgumentError, "cannot bind after first Sandbox invocation" if @sealed
31
-
32
- member_str = validate_member_name!(member)
33
- raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
34
-
35
- @members[member_str] = object
36
- self
37
- end
38
-
39
- # Mark this Namespace as sealed. Called by
40
- # +Kobako::Catalog::Namespaces#seal!+ on the owning Sandbox's first
41
- # invocation; afterwards #bind raises +ArgumentError+. Idempotent;
42
- # returns +self+.
43
- def seal!
44
- @sealed = true
45
- self
46
- end
47
-
48
- # Member lookup; raises +KeyError+ when no Member is registered
49
- # under +member+.
50
- def fetch(member)
51
- member_str = member.to_s
52
- unless @members.key?(member_str)
53
- raise KeyError,
54
- "no member named #{member_str.inspect} in namespace #{@name.inspect}"
55
- end
56
-
57
- @members[member_str]
58
- end
59
-
60
- # Structured description for the guest preamble (Frame 1). Returns a
61
- # two-element array +[name, member_keys]+ suitable for msgpack encoding.
62
- def to_preamble
63
- [@name, @members.keys]
64
- end
65
-
66
- private
67
-
68
- def validate_member_name!(member)
69
- member_str = member.to_s
70
- unless NAME_PATTERN.match?(member_str)
71
- raise ArgumentError,
72
- "MemberName must match #{NAME_PATTERN.inspect} (got #{member.inspect})"
73
- end
74
-
75
- member_str
76
- end
77
- end
78
- end
@@ -1,17 +0,0 @@
1
- module Kobako
2
- module Catalog
3
- class Namespaces
4
- def initialize: (?handler: Kobako::Catalog::Handles) -> void
5
-
6
- def define: (Symbol | String name) -> Kobako::Namespace
7
-
8
- def lookup: (String target) -> untyped
9
-
10
- def encode: () -> String
11
-
12
- def seal!: () -> self
13
-
14
- def sealed?: () -> bool
15
- end
16
- end
17
- end