typenative 0.6.1 → 0.7.0

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 (1004) hide show
  1. package/CHANGELOG.md +412 -0
  2. package/README.md +1 -1
  3. package/bin/cli.js +18 -8
  4. package/bin/go/overrides.js +21 -1
  5. package/bin/index.js +48 -25
  6. package/bin/main.js +2 -1
  7. package/bin/node/assert.js +54 -15
  8. package/bin/node/async_hooks.js +69 -10
  9. package/bin/node/buffer.js +321 -7
  10. package/bin/node/child_process.js +154 -8
  11. package/bin/node/cluster.js +436 -32
  12. package/bin/node/crypto.js +814 -5
  13. package/bin/node/crypto_curves.js +142 -0
  14. package/bin/node/crypto_keys.js +1147 -48
  15. package/bin/node/crypto_pem.js +313 -0
  16. package/bin/node/crypto_pkcs12.js +17 -0
  17. package/bin/node/dgram.js +161 -10
  18. package/bin/node/diagnostics_channel.js +5 -1
  19. package/bin/node/events.js +358 -8
  20. package/bin/node/ffi.js +933 -0
  21. package/bin/node/fs.js +334 -6
  22. package/bin/node/http.js +630 -55
  23. package/bin/node/http2.js +1141 -88
  24. package/bin/node/intl.js +4576 -0
  25. package/bin/node/intl_data.js +65412 -0
  26. package/bin/node/module_v8.js +155 -16
  27. package/bin/node/net.js +59 -10
  28. package/bin/node/path.js +5 -1
  29. package/bin/node/process.js +342 -3
  30. package/bin/node/readline.js +558 -8
  31. package/bin/node/registry.js +2 -0
  32. package/bin/node/sqlite.js +51 -2
  33. package/bin/node/stream.js +370 -32
  34. package/bin/node/stream_web.js +422 -15
  35. package/bin/node/system_extra.js +154 -1
  36. package/bin/node/temporal.js +96 -0
  37. package/bin/node/temporal_runtime.js +5075 -0
  38. package/bin/node/temporal_zones.js +460 -0
  39. package/bin/node/test.js +153 -8
  40. package/bin/node/test_coverage.js +58 -0
  41. package/bin/node/test_report.js +3 -3
  42. package/bin/node/test_run.js +7 -1
  43. package/bin/node/timers.js +123 -0
  44. package/bin/node/tls.js +346 -12
  45. package/bin/node/tls_roots.js +122 -0
  46. package/bin/node/typed_arrays.js +867 -93
  47. package/bin/node/url.js +657 -0
  48. package/bin/node/util.js +441 -2
  49. package/bin/node/util_extra.js +6 -0
  50. package/bin/node/wasi.js +214 -0
  51. package/bin/node/webassembly.js +1122 -0
  52. package/bin/node/websocket.js +763 -0
  53. package/bin/node/worker_threads.js +434 -52
  54. package/bin/node/zlib.js +338 -9
  55. package/bin/node/zlib_zip.js +2392 -0
  56. package/bin/transpiler.js +2083 -254
  57. package/bin/typecheck-node.js +49 -17
  58. package/bin/version.js +1 -1
  59. package/conformance.md +160 -113
  60. package/examples/README.md +21 -20
  61. package/examples/angular-templates/README.md +12 -12
  62. package/examples/desktop-notes/README.md +7 -7
  63. package/examples/dupe-finder/README.md +4 -4
  64. package/examples/fibonacci/README.md +6 -6
  65. package/examples/hello-world/README.md +4 -4
  66. package/examples/json-server/README.md +13 -12
  67. package/examples/mandelbrot-png/README.md +4 -4
  68. package/examples/marked-cli/README.md +16 -17
  69. package/examples/openai-chat/README.md +5 -5
  70. package/examples/react-compiler/README.md +10 -10
  71. package/examples/todo-cli/README.md +8 -8
  72. package/examples/yaml-cli/README.md +10 -10
  73. package/govendor/github.com/cloudflare/circl/.golangci.yaml +64 -0
  74. package/govendor/github.com/cloudflare/circl/.semgrepignore +1 -0
  75. package/govendor/github.com/cloudflare/circl/AGENTS.md +91 -0
  76. package/govendor/github.com/cloudflare/circl/CITATION.cff +30 -0
  77. package/govendor/github.com/cloudflare/circl/LICENSE +57 -0
  78. package/govendor/github.com/cloudflare/circl/Makefile +70 -0
  79. package/govendor/github.com/cloudflare/circl/README.md +206 -0
  80. package/govendor/github.com/cloudflare/circl/REVIEW.md +83 -0
  81. package/govendor/github.com/cloudflare/circl/codecov.yml +21 -0
  82. package/govendor/github.com/cloudflare/circl/dh/x448/curve.go +104 -0
  83. package/govendor/github.com/cloudflare/circl/dh/x448/curve_amd64.go +30 -0
  84. package/govendor/github.com/cloudflare/circl/dh/x448/curve_amd64.h +111 -0
  85. package/govendor/github.com/cloudflare/circl/dh/x448/curve_amd64.s +194 -0
  86. package/govendor/github.com/cloudflare/circl/dh/x448/curve_generic.go +100 -0
  87. package/govendor/github.com/cloudflare/circl/dh/x448/curve_noasm.go +11 -0
  88. package/govendor/github.com/cloudflare/circl/dh/x448/doc.go +19 -0
  89. package/govendor/github.com/cloudflare/circl/dh/x448/key.go +46 -0
  90. package/govendor/github.com/cloudflare/circl/dh/x448/table.go +460 -0
  91. package/govendor/github.com/cloudflare/circl/doc.go +8 -0
  92. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/constants.go +71 -0
  93. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/curve.go +90 -0
  94. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/isogeny.go +52 -0
  95. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/point.go +181 -0
  96. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/scalar.go +203 -0
  97. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/twist.go +138 -0
  98. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/twistPoint.go +135 -0
  99. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/twistTables.go +216 -0
  100. package/govendor/github.com/cloudflare/circl/ecc/goldilocks/twist_basemult.go +62 -0
  101. package/govendor/github.com/cloudflare/circl/go.mod +3 -0
  102. package/govendor/github.com/cloudflare/circl/internal/conv/conv.go +173 -0
  103. package/govendor/github.com/cloudflare/circl/internal/sha3/doc.go +62 -0
  104. package/govendor/github.com/cloudflare/circl/internal/sha3/hashes.go +69 -0
  105. package/govendor/github.com/cloudflare/circl/internal/sha3/keccakf.go +391 -0
  106. package/govendor/github.com/cloudflare/circl/internal/sha3/rc.go +29 -0
  107. package/govendor/github.com/cloudflare/circl/internal/sha3/sha3.go +200 -0
  108. package/govendor/github.com/cloudflare/circl/internal/sha3/sha3_s390x.s +33 -0
  109. package/govendor/github.com/cloudflare/circl/internal/sha3/shake.go +119 -0
  110. package/govendor/github.com/cloudflare/circl/internal/sha3/xor.go +15 -0
  111. package/govendor/github.com/cloudflare/circl/internal/sha3/xor_generic.go +33 -0
  112. package/govendor/github.com/cloudflare/circl/internal/sha3/xor_unaligned.go +61 -0
  113. package/govendor/github.com/cloudflare/circl/math/fp448/fp.go +164 -0
  114. package/govendor/github.com/cloudflare/circl/math/fp448/fp_amd64.go +43 -0
  115. package/govendor/github.com/cloudflare/circl/math/fp448/fp_amd64.h +591 -0
  116. package/govendor/github.com/cloudflare/circl/math/fp448/fp_amd64.s +75 -0
  117. package/govendor/github.com/cloudflare/circl/math/fp448/fp_generic.go +339 -0
  118. package/govendor/github.com/cloudflare/circl/math/fp448/fp_noasm.go +12 -0
  119. package/govendor/github.com/cloudflare/circl/math/fp448/fuzzer.go +75 -0
  120. package/govendor/github.com/cloudflare/circl/math/integer.go +16 -0
  121. package/govendor/github.com/cloudflare/circl/math/mlsbset/mlsbset.go +145 -0
  122. package/govendor/github.com/cloudflare/circl/math/mlsbset/power.go +64 -0
  123. package/govendor/github.com/cloudflare/circl/math/primes.go +34 -0
  124. package/govendor/github.com/cloudflare/circl/math/wnaf.go +84 -0
  125. package/govendor/github.com/cloudflare/circl/sign/ed448/ed448.go +417 -0
  126. package/govendor/github.com/cloudflare/circl/sign/ed448/signapi.go +89 -0
  127. package/govendor/github.com/cloudflare/circl/sign/sign.go +119 -0
  128. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/LICENSE +17 -0
  129. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/README.md +72 -0
  130. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/compressedbytepoints.go +18 -0
  131. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/curve.go +1310 -0
  132. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/curve_embedded.go +14 -0
  133. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/curve_precompute.go +14 -0
  134. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/doc.go +59 -0
  135. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ecdh.go +21 -0
  136. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa/README.md +52 -0
  137. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa/doc.go +42 -0
  138. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa/error.go +134 -0
  139. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa/signature.go +1001 -0
  140. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/ellipticadaptor.go +296 -0
  141. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/error.go +67 -0
  142. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/field.go +1696 -0
  143. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/go.mod +3 -0
  144. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/loadprecomputed.go +91 -0
  145. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/modnscalar.go +1105 -0
  146. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/nonce.go +263 -0
  147. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/privkey.go +111 -0
  148. package/govendor/github.com/decred/dcrd/dcrec/secp256k1/v4/pubkey.go +236 -0
  149. package/govendor/github.com/ebitengine/purego/LICENSE +201 -0
  150. package/govendor/github.com/ebitengine/purego/README.md +124 -0
  151. package/govendor/github.com/ebitengine/purego/abi_amd64.h +99 -0
  152. package/govendor/github.com/ebitengine/purego/abi_arm64.h +39 -0
  153. package/govendor/github.com/ebitengine/purego/abi_loong64.h +60 -0
  154. package/govendor/github.com/ebitengine/purego/cdecl.go +11 -0
  155. package/govendor/github.com/ebitengine/purego/cgo.go +19 -0
  156. package/govendor/github.com/ebitengine/purego/dlerror.go +17 -0
  157. package/govendor/github.com/ebitengine/purego/dlfcn.go +99 -0
  158. package/govendor/github.com/ebitengine/purego/dlfcn_android.go +34 -0
  159. package/govendor/github.com/ebitengine/purego/dlfcn_darwin.go +20 -0
  160. package/govendor/github.com/ebitengine/purego/dlfcn_freebsd.go +14 -0
  161. package/govendor/github.com/ebitengine/purego/dlfcn_linux.go +16 -0
  162. package/govendor/github.com/ebitengine/purego/dlfcn_netbsd.go +15 -0
  163. package/govendor/github.com/ebitengine/purego/dlfcn_nocgo_freebsd.go +11 -0
  164. package/govendor/github.com/ebitengine/purego/dlfcn_nocgo_linux.go +19 -0
  165. package/govendor/github.com/ebitengine/purego/dlfcn_nocgo_netbsd.go +11 -0
  166. package/govendor/github.com/ebitengine/purego/dlfcn_playground.go +24 -0
  167. package/govendor/github.com/ebitengine/purego/dlfcn_stubs.s +22 -0
  168. package/govendor/github.com/ebitengine/purego/func.go +780 -0
  169. package/govendor/github.com/ebitengine/purego/gen.go +6 -0
  170. package/govendor/github.com/ebitengine/purego/go.mod +3 -0
  171. package/govendor/github.com/ebitengine/purego/go_runtime.go +19 -0
  172. package/govendor/github.com/ebitengine/purego/internal/cgo/dlfcn_cgo_unix.go +56 -0
  173. package/govendor/github.com/ebitengine/purego/internal/cgo/empty.go +6 -0
  174. package/govendor/github.com/ebitengine/purego/internal/cgo/syscall_cgo_unix.go +49 -0
  175. package/govendor/github.com/ebitengine/purego/internal/fakecgo/abi_amd64.h +99 -0
  176. package/govendor/github.com/ebitengine/purego/internal/fakecgo/abi_arm64.h +39 -0
  177. package/govendor/github.com/ebitengine/purego/internal/fakecgo/abi_loong64.h +60 -0
  178. package/govendor/github.com/ebitengine/purego/internal/fakecgo/abi_ppc64x.h +195 -0
  179. package/govendor/github.com/ebitengine/purego/internal/fakecgo/abi_riscv64.h +72 -0
  180. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_386.s +29 -0
  181. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_amd64.s +39 -0
  182. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_arm.s +58 -0
  183. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_arm64.s +35 -0
  184. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_loong64.s +38 -0
  185. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_ppc64le.s +79 -0
  186. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_riscv64.s +36 -0
  187. package/govendor/github.com/ebitengine/purego/internal/fakecgo/asm_s390x.s +52 -0
  188. package/govendor/github.com/ebitengine/purego/internal/fakecgo/callbacks.go +93 -0
  189. package/govendor/github.com/ebitengine/purego/internal/fakecgo/doc.go +32 -0
  190. package/govendor/github.com/ebitengine/purego/internal/fakecgo/fakecgo.go +14 -0
  191. package/govendor/github.com/ebitengine/purego/internal/fakecgo/freebsd.go +27 -0
  192. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_darwin.go +86 -0
  193. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_freebsd.go +77 -0
  194. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_libinit.go +72 -0
  195. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_linux.go +77 -0
  196. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_netbsd.go +83 -0
  197. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_setenv.go +18 -0
  198. package/govendor/github.com/ebitengine/purego/internal/fakecgo/go_util.go +38 -0
  199. package/govendor/github.com/ebitengine/purego/internal/fakecgo/iscgo.go +19 -0
  200. package/govendor/github.com/ebitengine/purego/internal/fakecgo/libcgo.go +37 -0
  201. package/govendor/github.com/ebitengine/purego/internal/fakecgo/libcgo_darwin.go +37 -0
  202. package/govendor/github.com/ebitengine/purego/internal/fakecgo/libcgo_freebsd.go +27 -0
  203. package/govendor/github.com/ebitengine/purego/internal/fakecgo/libcgo_linux.go +27 -0
  204. package/govendor/github.com/ebitengine/purego/internal/fakecgo/libcgo_netbsd.go +36 -0
  205. package/govendor/github.com/ebitengine/purego/internal/fakecgo/linux.go +189 -0
  206. package/govendor/github.com/ebitengine/purego/internal/fakecgo/netbsd.go +23 -0
  207. package/govendor/github.com/ebitengine/purego/internal/fakecgo/setenv.go +19 -0
  208. package/govendor/github.com/ebitengine/purego/internal/fakecgo/threadentry_amd64.go +15 -0
  209. package/govendor/github.com/ebitengine/purego/internal/fakecgo/threadentry_noasm.go +24 -0
  210. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_386.s +130 -0
  211. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_amd64.s +124 -0
  212. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_arm.s +131 -0
  213. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_arm64.s +81 -0
  214. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_386.s +78 -0
  215. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_amd64.s +69 -0
  216. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_arm.s +69 -0
  217. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_arm64.s +60 -0
  218. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_loong64.s +60 -0
  219. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_ppc64le.s +69 -0
  220. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_riscv64.s +60 -0
  221. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_linux_s390x.s +51 -0
  222. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_loong64.s +78 -0
  223. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_ppc64le.s +132 -0
  224. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_riscv64.s +76 -0
  225. package/govendor/github.com/ebitengine/purego/internal/fakecgo/trampolines_s390x.s +158 -0
  226. package/govendor/github.com/ebitengine/purego/internal/fakecgo/zsymbols.go +165 -0
  227. package/govendor/github.com/ebitengine/purego/internal/fakecgo/zsymbols_darwin.go +59 -0
  228. package/govendor/github.com/ebitengine/purego/internal/fakecgo/zsymbols_freebsd.go +48 -0
  229. package/govendor/github.com/ebitengine/purego/internal/fakecgo/zsymbols_linux.go +158 -0
  230. package/govendor/github.com/ebitengine/purego/internal/fakecgo/zsymbols_netbsd.go +59 -0
  231. package/govendor/github.com/ebitengine/purego/internal/fakecgo/ztrampolines_darwin.s +19 -0
  232. package/govendor/github.com/ebitengine/purego/internal/fakecgo/ztrampolines_freebsd.s +16 -0
  233. package/govendor/github.com/ebitengine/purego/internal/fakecgo/ztrampolines_linux.s +46 -0
  234. package/govendor/github.com/ebitengine/purego/internal/fakecgo/ztrampolines_netbsd.s +19 -0
  235. package/govendor/github.com/ebitengine/purego/internal/fakecgo/ztrampolines_stubs.s +55 -0
  236. package/govendor/github.com/ebitengine/purego/internal/strings/strings.go +40 -0
  237. package/govendor/github.com/ebitengine/purego/is_ios.go +13 -0
  238. package/govendor/github.com/ebitengine/purego/nocgo.go +25 -0
  239. package/govendor/github.com/ebitengine/purego/struct_amd64.go +518 -0
  240. package/govendor/github.com/ebitengine/purego/struct_arm.go +100 -0
  241. package/govendor/github.com/ebitengine/purego/struct_arm64.go +757 -0
  242. package/govendor/github.com/ebitengine/purego/struct_loong64.go +244 -0
  243. package/govendor/github.com/ebitengine/purego/struct_other.go +54 -0
  244. package/govendor/github.com/ebitengine/purego/struct_ppc64le.go +180 -0
  245. package/govendor/github.com/ebitengine/purego/struct_riscv64.go +158 -0
  246. package/govendor/github.com/ebitengine/purego/struct_s390x.go +158 -0
  247. package/govendor/github.com/ebitengine/purego/sys_386.s +153 -0
  248. package/govendor/github.com/ebitengine/purego/sys_amd64.s +206 -0
  249. package/govendor/github.com/ebitengine/purego/sys_arm.s +153 -0
  250. package/govendor/github.com/ebitengine/purego/sys_arm64.s +133 -0
  251. package/govendor/github.com/ebitengine/purego/sys_loong64.s +131 -0
  252. package/govendor/github.com/ebitengine/purego/sys_ppc64le.s +126 -0
  253. package/govendor/github.com/ebitengine/purego/sys_riscv64.s +135 -0
  254. package/govendor/github.com/ebitengine/purego/sys_s390x.s +148 -0
  255. package/govendor/github.com/ebitengine/purego/sys_unix_386.s +234 -0
  256. package/govendor/github.com/ebitengine/purego/sys_unix_arm.s +99 -0
  257. package/govendor/github.com/ebitengine/purego/sys_unix_arm64.s +75 -0
  258. package/govendor/github.com/ebitengine/purego/sys_unix_loong64.s +79 -0
  259. package/govendor/github.com/ebitengine/purego/sys_unix_ppc64le.s +114 -0
  260. package/govendor/github.com/ebitengine/purego/sys_unix_riscv64.s +79 -0
  261. package/govendor/github.com/ebitengine/purego/sys_unix_s390x.s +111 -0
  262. package/govendor/github.com/ebitengine/purego/syscall.go +95 -0
  263. package/govendor/github.com/ebitengine/purego/syscall_32bit.go +97 -0
  264. package/govendor/github.com/ebitengine/purego/syscall_cgo_linux.go +20 -0
  265. package/govendor/github.com/ebitengine/purego/syscall_notstackargs.go +55 -0
  266. package/govendor/github.com/ebitengine/purego/syscall_ppc64le.go +73 -0
  267. package/govendor/github.com/ebitengine/purego/syscall_stackargs_ppc64le.go +38 -0
  268. package/govendor/github.com/ebitengine/purego/syscall_stackargs_s390x.go +38 -0
  269. package/govendor/github.com/ebitengine/purego/syscall_unix.go +392 -0
  270. package/govendor/github.com/ebitengine/purego/syscall_windows.go +54 -0
  271. package/govendor/github.com/ebitengine/purego/zcallback_386.s +4014 -0
  272. package/govendor/github.com/ebitengine/purego/zcallback_amd64.s +2014 -0
  273. package/govendor/github.com/ebitengine/purego/zcallback_arm.s +4014 -0
  274. package/govendor/github.com/ebitengine/purego/zcallback_arm64.s +4014 -0
  275. package/govendor/github.com/ebitengine/purego/zcallback_loong64.s +4014 -0
  276. package/govendor/github.com/ebitengine/purego/zcallback_ppc64le.s +4014 -0
  277. package/govendor/github.com/ebitengine/purego/zcallback_riscv64.s +4051 -0
  278. package/govendor/github.com/ebitengine/purego/zcallback_s390x.s +4015 -0
  279. package/govendor/github.com/klauspost/compress/.gitattributes +3 -0
  280. package/govendor/github.com/klauspost/compress/.goreleaser.yml +132 -0
  281. package/govendor/github.com/klauspost/compress/AGENTS.md +106 -0
  282. package/govendor/github.com/klauspost/compress/LICENSE +304 -0
  283. package/govendor/github.com/klauspost/compress/README.md +766 -0
  284. package/govendor/github.com/klauspost/compress/SECURITY.md +25 -0
  285. package/govendor/github.com/klauspost/compress/compressible.go +85 -0
  286. package/govendor/github.com/klauspost/compress/fse/README.md +79 -0
  287. package/govendor/github.com/klauspost/compress/fse/bitreader.go +122 -0
  288. package/govendor/github.com/klauspost/compress/fse/bitwriter.go +167 -0
  289. package/govendor/github.com/klauspost/compress/fse/bytereader.go +47 -0
  290. package/govendor/github.com/klauspost/compress/fse/compress.go +685 -0
  291. package/govendor/github.com/klauspost/compress/fse/decompress.go +383 -0
  292. package/govendor/github.com/klauspost/compress/fse/fse.go +150 -0
  293. package/govendor/github.com/klauspost/compress/gen.sh +4 -0
  294. package/govendor/github.com/klauspost/compress/go.mod +3 -0
  295. package/govendor/github.com/klauspost/compress/huff0/README.md +89 -0
  296. package/govendor/github.com/klauspost/compress/huff0/bitreader.go +323 -0
  297. package/govendor/github.com/klauspost/compress/huff0/bitwriter.go +97 -0
  298. package/govendor/github.com/klauspost/compress/huff0/build_table.go +168 -0
  299. package/govendor/github.com/klauspost/compress/huff0/compress.go +747 -0
  300. package/govendor/github.com/klauspost/compress/huff0/decompress.go +1188 -0
  301. package/govendor/github.com/klauspost/compress/huff0/decompress_amd64.go +128 -0
  302. package/govendor/github.com/klauspost/compress/huff0/decompress_amd64.s +3476 -0
  303. package/govendor/github.com/klauspost/compress/huff0/decompress_arm64.go +72 -0
  304. package/govendor/github.com/klauspost/compress/huff0/decompress_arm64.s +1648 -0
  305. package/govendor/github.com/klauspost/compress/huff0/decompress_asm.go +252 -0
  306. package/govendor/github.com/klauspost/compress/huff0/decompress_generic.go +278 -0
  307. package/govendor/github.com/klauspost/compress/huff0/huff0.go +337 -0
  308. package/govendor/github.com/klauspost/compress/internal/cpuinfo/cpuinfo.go +34 -0
  309. package/govendor/github.com/klauspost/compress/internal/cpuinfo/cpuinfo_amd64.go +10 -0
  310. package/govendor/github.com/klauspost/compress/internal/cpuinfo/cpuinfo_amd64.s +34 -0
  311. package/govendor/github.com/klauspost/compress/internal/le/le.go +5 -0
  312. package/govendor/github.com/klauspost/compress/internal/le/unsafe_disabled.go +42 -0
  313. package/govendor/github.com/klauspost/compress/internal/le/unsafe_enabled.go +52 -0
  314. package/govendor/github.com/klauspost/compress/internal/regmask/regmask.go +50 -0
  315. package/govendor/github.com/klauspost/compress/internal/regmask/regmask_386.go +39 -0
  316. package/govendor/github.com/klauspost/compress/internal/snapref/LICENSE +27 -0
  317. package/govendor/github.com/klauspost/compress/internal/snapref/decode.go +264 -0
  318. package/govendor/github.com/klauspost/compress/internal/snapref/decode_other.go +113 -0
  319. package/govendor/github.com/klauspost/compress/internal/snapref/encode.go +291 -0
  320. package/govendor/github.com/klauspost/compress/internal/snapref/encode_other.go +250 -0
  321. package/govendor/github.com/klauspost/compress/internal/snapref/snappy.go +98 -0
  322. package/govendor/github.com/klauspost/compress/s2sx.mod +3 -0
  323. package/govendor/github.com/klauspost/compress/s2sx.sum +0 -0
  324. package/govendor/github.com/klauspost/compress/zstd/README.md +487 -0
  325. package/govendor/github.com/klauspost/compress/zstd/bitreader.go +176 -0
  326. package/govendor/github.com/klauspost/compress/zstd/bitwriter.go +151 -0
  327. package/govendor/github.com/klauspost/compress/zstd/blockdec.go +728 -0
  328. package/govendor/github.com/klauspost/compress/zstd/blockenc.go +923 -0
  329. package/govendor/github.com/klauspost/compress/zstd/blocktype_string.go +85 -0
  330. package/govendor/github.com/klauspost/compress/zstd/bytebuf.go +131 -0
  331. package/govendor/github.com/klauspost/compress/zstd/bytereader.go +82 -0
  332. package/govendor/github.com/klauspost/compress/zstd/decodeheader.go +261 -0
  333. package/govendor/github.com/klauspost/compress/zstd/decoder.go +995 -0
  334. package/govendor/github.com/klauspost/compress/zstd/decoder_options.go +213 -0
  335. package/govendor/github.com/klauspost/compress/zstd/dict.go +605 -0
  336. package/govendor/github.com/klauspost/compress/zstd/enc_base.go +200 -0
  337. package/govendor/github.com/klauspost/compress/zstd/enc_best.go +572 -0
  338. package/govendor/github.com/klauspost/compress/zstd/enc_better.go +1262 -0
  339. package/govendor/github.com/klauspost/compress/zstd/enc_dfast.go +1136 -0
  340. package/govendor/github.com/klauspost/compress/zstd/enc_fast.go +892 -0
  341. package/govendor/github.com/klauspost/compress/zstd/enc_jobs.go +352 -0
  342. package/govendor/github.com/klauspost/compress/zstd/encoder.go +881 -0
  343. package/govendor/github.com/klauspost/compress/zstd/encoder_options.go +422 -0
  344. package/govendor/github.com/klauspost/compress/zstd/framedec.go +404 -0
  345. package/govendor/github.com/klauspost/compress/zstd/frameenc.go +137 -0
  346. package/govendor/github.com/klauspost/compress/zstd/fse_decoder.go +333 -0
  347. package/govendor/github.com/klauspost/compress/zstd/fse_decoder_amd64.s +132 -0
  348. package/govendor/github.com/klauspost/compress/zstd/fse_decoder_arm64.s +148 -0
  349. package/govendor/github.com/klauspost/compress/zstd/fse_decoder_asm.go +70 -0
  350. package/govendor/github.com/klauspost/compress/zstd/fse_decoder_generic.go +71 -0
  351. package/govendor/github.com/klauspost/compress/zstd/fse_encoder.go +701 -0
  352. package/govendor/github.com/klauspost/compress/zstd/fse_predefined.go +168 -0
  353. package/govendor/github.com/klauspost/compress/zstd/hash.go +57 -0
  354. package/govendor/github.com/klauspost/compress/zstd/history.go +119 -0
  355. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/LICENSE.txt +22 -0
  356. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/README.md +71 -0
  357. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash.go +242 -0
  358. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash_amd64.s +210 -0
  359. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash_arm64.s +184 -0
  360. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash_asm.go +11 -0
  361. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash_other.go +75 -0
  362. package/govendor/github.com/klauspost/compress/zstd/internal/xxhash/xxhash_safe.go +11 -0
  363. package/govendor/github.com/klauspost/compress/zstd/matchlen_amd64.go +15 -0
  364. package/govendor/github.com/klauspost/compress/zstd/matchlen_amd64.s +66 -0
  365. package/govendor/github.com/klauspost/compress/zstd/matchlen_generic.go +37 -0
  366. package/govendor/github.com/klauspost/compress/zstd/seqdec.go +620 -0
  367. package/govendor/github.com/klauspost/compress/zstd/seqdec_amd64.go +115 -0
  368. package/govendor/github.com/klauspost/compress/zstd/seqdec_amd64.s +4762 -0
  369. package/govendor/github.com/klauspost/compress/zstd/seqdec_arm64.go +81 -0
  370. package/govendor/github.com/klauspost/compress/zstd/seqdec_arm64.s +2919 -0
  371. package/govendor/github.com/klauspost/compress/zstd/seqdec_asm.go +327 -0
  372. package/govendor/github.com/klauspost/compress/zstd/seqdec_generic.go +258 -0
  373. package/govendor/github.com/klauspost/compress/zstd/seqenc.go +159 -0
  374. package/govendor/github.com/klauspost/compress/zstd/simple.go +54 -0
  375. package/govendor/github.com/klauspost/compress/zstd/snappy.go +447 -0
  376. package/govendor/github.com/klauspost/compress/zstd/zip.go +141 -0
  377. package/govendor/github.com/klauspost/compress/zstd/zstd.go +126 -0
  378. package/govendor/github.com/tetratelabs/wazero/.editorconfig +7 -0
  379. package/govendor/github.com/tetratelabs/wazero/.gitattributes +2 -0
  380. package/govendor/github.com/tetratelabs/wazero/.gitmodules +3 -0
  381. package/govendor/github.com/tetratelabs/wazero/CONTRIBUTING.md +75 -0
  382. package/govendor/github.com/tetratelabs/wazero/LICENSE +201 -0
  383. package/govendor/github.com/tetratelabs/wazero/Makefile +385 -0
  384. package/govendor/github.com/tetratelabs/wazero/NOTICE +2 -0
  385. package/govendor/github.com/tetratelabs/wazero/RATIONALE.md +1577 -0
  386. package/govendor/github.com/tetratelabs/wazero/README.md +135 -0
  387. package/govendor/github.com/tetratelabs/wazero/api/features.go +228 -0
  388. package/govendor/github.com/tetratelabs/wazero/api/wasm.go +766 -0
  389. package/govendor/github.com/tetratelabs/wazero/builder.go +367 -0
  390. package/govendor/github.com/tetratelabs/wazero/cache.go +123 -0
  391. package/govendor/github.com/tetratelabs/wazero/codecov.yml +9 -0
  392. package/govendor/github.com/tetratelabs/wazero/config.go +899 -0
  393. package/govendor/github.com/tetratelabs/wazero/experimental/checkpoint.go +35 -0
  394. package/govendor/github.com/tetratelabs/wazero/experimental/close.go +63 -0
  395. package/govendor/github.com/tetratelabs/wazero/experimental/compilationworkers.go +19 -0
  396. package/govendor/github.com/tetratelabs/wazero/experimental/experimental.go +41 -0
  397. package/govendor/github.com/tetratelabs/wazero/experimental/features.go +39 -0
  398. package/govendor/github.com/tetratelabs/wazero/experimental/importresolver.go +19 -0
  399. package/govendor/github.com/tetratelabs/wazero/experimental/listener.go +324 -0
  400. package/govendor/github.com/tetratelabs/wazero/experimental/memory.go +52 -0
  401. package/govendor/github.com/tetratelabs/wazero/experimental/sys/dir.go +92 -0
  402. package/govendor/github.com/tetratelabs/wazero/experimental/sys/errno.go +98 -0
  403. package/govendor/github.com/tetratelabs/wazero/experimental/sys/error.go +45 -0
  404. package/govendor/github.com/tetratelabs/wazero/experimental/sys/file.go +356 -0
  405. package/govendor/github.com/tetratelabs/wazero/experimental/sys/fs.go +292 -0
  406. package/govendor/github.com/tetratelabs/wazero/experimental/sys/oflag.go +70 -0
  407. package/govendor/github.com/tetratelabs/wazero/experimental/sys/poll.go +48 -0
  408. package/govendor/github.com/tetratelabs/wazero/experimental/sys/syscall_errno.go +106 -0
  409. package/govendor/github.com/tetratelabs/wazero/experimental/sys/syscall_errno_notwindows.go +13 -0
  410. package/govendor/github.com/tetratelabs/wazero/experimental/sys/syscall_errno_unsupported.go +7 -0
  411. package/govendor/github.com/tetratelabs/wazero/experimental/sys/syscall_errno_windows.go +37 -0
  412. package/govendor/github.com/tetratelabs/wazero/experimental/sys/time.go +10 -0
  413. package/govendor/github.com/tetratelabs/wazero/experimental/sys/unimplemented.go +160 -0
  414. package/govendor/github.com/tetratelabs/wazero/fsconfig.go +213 -0
  415. package/govendor/github.com/tetratelabs/wazero/go.mod +3 -0
  416. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/args.go +97 -0
  417. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/clock.go +116 -0
  418. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/environ.go +100 -0
  419. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/fs.go +2015 -0
  420. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/poll.go +247 -0
  421. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/proc.go +44 -0
  422. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/random.go +55 -0
  423. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/sched.go +22 -0
  424. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/sock.go +188 -0
  425. package/govendor/github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1/wasi.go +314 -0
  426. package/govendor/github.com/tetratelabs/wazero/internal/descriptor/table.go +149 -0
  427. package/govendor/github.com/tetratelabs/wazero/internal/engine/interpreter/compiler.go +3884 -0
  428. package/govendor/github.com/tetratelabs/wazero/internal/engine/interpreter/format.go +22 -0
  429. package/govendor/github.com/tetratelabs/wazero/internal/engine/interpreter/interpreter.go +4963 -0
  430. package/govendor/github.com/tetratelabs/wazero/internal/engine/interpreter/operations.go +2978 -0
  431. package/govendor/github.com/tetratelabs/wazero/internal/engine/interpreter/signature.go +825 -0
  432. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/abi.go +170 -0
  433. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/backend.go +3 -0
  434. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/compiler.go +402 -0
  435. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/compiler_lower.go +226 -0
  436. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/go_call.go +33 -0
  437. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/abi.go +186 -0
  438. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/abi_entry_amd64.go +9 -0
  439. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/abi_entry_amd64.s +29 -0
  440. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/abi_entry_preamble.go +248 -0
  441. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/abi_go_call.go +440 -0
  442. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/cond.go +168 -0
  443. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/ext.go +35 -0
  444. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/instr.go +2495 -0
  445. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/instr_encoding.go +1714 -0
  446. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/lower_constant.go +71 -0
  447. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/lower_mem.go +187 -0
  448. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/machine.go +3782 -0
  449. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/machine_pro_epi_logue.go +334 -0
  450. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/machine_regalloc.go +352 -0
  451. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/machine_vec.go +992 -0
  452. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/operands.go +336 -0
  453. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/reg.go +181 -0
  454. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/amd64/stack.go +130 -0
  455. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/abi.go +376 -0
  456. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/abi_entry_arm64.go +9 -0
  457. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/abi_entry_arm64.s +29 -0
  458. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/abi_entry_preamble.go +233 -0
  459. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/abi_go_call.go +430 -0
  460. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/cond.go +215 -0
  461. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/instr.go +2562 -0
  462. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/instr_encoding.go +2357 -0
  463. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/lower_constant.go +301 -0
  464. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/lower_instr.go +2227 -0
  465. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/lower_instr_operands.go +340 -0
  466. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/lower_mem.go +451 -0
  467. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/machine.go +631 -0
  468. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/machine_pro_epi_logue.go +486 -0
  469. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/machine_regalloc.go +351 -0
  470. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/machine_relocation.go +128 -0
  471. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/reg.go +397 -0
  472. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/isa/arm64/unwind_stack.go +84 -0
  473. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/machine.go +119 -0
  474. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/regalloc/api.go +124 -0
  475. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/regalloc/reg.go +123 -0
  476. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/regalloc/regalloc.go +1189 -0
  477. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/regalloc/regset.go +96 -0
  478. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/backend/vdef.go +19 -0
  479. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/call_engine.go +884 -0
  480. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/engine.go +1008 -0
  481. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/engine_cache.go +347 -0
  482. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/entrypoint_amd64.go +13 -0
  483. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/entrypoint_arm64.go +13 -0
  484. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/entrypoint_other.go +15 -0
  485. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/frontend/frontend.go +663 -0
  486. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/frontend/lower.go +5045 -0
  487. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/frontend/misc.go +10 -0
  488. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/frontend/sort_id.go +13 -0
  489. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/hostmodule.go +88 -0
  490. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/isa_amd64.go +30 -0
  491. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/isa_arm64.go +32 -0
  492. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/isa_other.go +29 -0
  493. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/memmove.go +11 -0
  494. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/module_engine.go +403 -0
  495. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/basic_block.go +381 -0
  496. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/basic_block_sort.go +32 -0
  497. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/builder.go +790 -0
  498. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/cmp.go +107 -0
  499. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/funcref.go +12 -0
  500. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/instructions.go +3024 -0
  501. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/pass.go +393 -0
  502. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/pass_blk_layouts.go +334 -0
  503. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/pass_cfg.go +313 -0
  504. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/signature.go +49 -0
  505. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/ssa.go +14 -0
  506. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/type.go +115 -0
  507. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/ssa/vs.go +114 -0
  508. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/debug_options.go +189 -0
  509. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/exitcode.go +150 -0
  510. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/offsetdata.go +248 -0
  511. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/perfmap.go +96 -0
  512. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/perfmap_disabled.go +5 -0
  513. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/perfmap_enabled.go +5 -0
  514. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/pool.go +215 -0
  515. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/ptr.go +15 -0
  516. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/queue.go +26 -0
  517. package/govendor/github.com/tetratelabs/wazero/internal/engine/wazevo/wazevoapi/resetmap.go +11 -0
  518. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/checkpoint.go +10 -0
  519. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/close.go +5 -0
  520. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/compilationworkers.go +6 -0
  521. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/expctxkeys.go +2 -0
  522. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/importresolver.go +6 -0
  523. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/listener.go +7 -0
  524. package/govendor/github.com/tetratelabs/wazero/internal/expctxkeys/memory.go +4 -0
  525. package/govendor/github.com/tetratelabs/wazero/internal/filecache/compilationcache.go +42 -0
  526. package/govendor/github.com/tetratelabs/wazero/internal/filecache/file_cache.go +76 -0
  527. package/govendor/github.com/tetratelabs/wazero/internal/ieee754/ieee754.go +29 -0
  528. package/govendor/github.com/tetratelabs/wazero/internal/internalapi/internal.go +9 -0
  529. package/govendor/github.com/tetratelabs/wazero/internal/leb128/leb128.go +285 -0
  530. package/govendor/github.com/tetratelabs/wazero/internal/moremath/moremath.go +271 -0
  531. package/govendor/github.com/tetratelabs/wazero/internal/platform/cpuid.go +26 -0
  532. package/govendor/github.com/tetratelabs/wazero/internal/platform/cpuid_amd64.go +22 -0
  533. package/govendor/github.com/tetratelabs/wazero/internal/platform/cpuid_arm64.go +13 -0
  534. package/govendor/github.com/tetratelabs/wazero/internal/platform/cpuid_unsupported.go +5 -0
  535. package/govendor/github.com/tetratelabs/wazero/internal/platform/crypto.go +17 -0
  536. package/govendor/github.com/tetratelabs/wazero/internal/platform/mmap_linux.go +72 -0
  537. package/govendor/github.com/tetratelabs/wazero/internal/platform/mmap_other.go +19 -0
  538. package/govendor/github.com/tetratelabs/wazero/internal/platform/mmap_unix.go +14 -0
  539. package/govendor/github.com/tetratelabs/wazero/internal/platform/mmap_unsupported.go +22 -0
  540. package/govendor/github.com/tetratelabs/wazero/internal/platform/mmap_windows.go +31 -0
  541. package/govendor/github.com/tetratelabs/wazero/internal/platform/path.go +6 -0
  542. package/govendor/github.com/tetratelabs/wazero/internal/platform/path_windows.go +17 -0
  543. package/govendor/github.com/tetratelabs/wazero/internal/platform/platform.go +71 -0
  544. package/govendor/github.com/tetratelabs/wazero/internal/platform/time.go +76 -0
  545. package/govendor/github.com/tetratelabs/wazero/internal/platform/time_notwindows.go +11 -0
  546. package/govendor/github.com/tetratelabs/wazero/internal/platform/time_windows.go +40 -0
  547. package/govendor/github.com/tetratelabs/wazero/internal/sock/sock.go +89 -0
  548. package/govendor/github.com/tetratelabs/wazero/internal/sock/sock_supported.go +11 -0
  549. package/govendor/github.com/tetratelabs/wazero/internal/sock/sock_unsupported.go +10 -0
  550. package/govendor/github.com/tetratelabs/wazero/internal/sys/fs.go +458 -0
  551. package/govendor/github.com/tetratelabs/wazero/internal/sys/lazy.go +135 -0
  552. package/govendor/github.com/tetratelabs/wazero/internal/sys/stdio.go +125 -0
  553. package/govendor/github.com/tetratelabs/wazero/internal/sys/sys.go +228 -0
  554. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/adapter.go +105 -0
  555. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/datasync_linux.go +12 -0
  556. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/datasync_unsupported.go +14 -0
  557. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/dir.go +24 -0
  558. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/dirfs.go +137 -0
  559. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/file.go +576 -0
  560. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/file_unix.go +39 -0
  561. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/file_unsupported.go +28 -0
  562. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/file_windows.go +133 -0
  563. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens.go +29 -0
  564. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens_darwin.go +42 -0
  565. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens_darwin.s +8 -0
  566. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens_linux.go +38 -0
  567. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens_unsupported.go +18 -0
  568. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/futimens_windows.go +42 -0
  569. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/ino_unix.go +22 -0
  570. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/ino_unsupported.go +17 -0
  571. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/ino_windows.go +28 -0
  572. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/nonblock_unix.go +17 -0
  573. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/nonblock_unsupported.go +13 -0
  574. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/nonblock_windows.go +23 -0
  575. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/oflag.go +38 -0
  576. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_bsd.go +26 -0
  577. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_darwin.go +26 -0
  578. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_supported.go +30 -0
  579. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_unix.go +20 -0
  580. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_unsupported.go +16 -0
  581. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/open_file_windows.go +163 -0
  582. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/osfile.go +318 -0
  583. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll.go +17 -0
  584. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll_darwin.go +55 -0
  585. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll_darwin.s +8 -0
  586. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll_linux.go +57 -0
  587. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll_unsupported.go +12 -0
  588. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/poll_windows.go +224 -0
  589. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/readfs.go +117 -0
  590. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/rename_unix.go +16 -0
  591. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/rename_unsupported.go +16 -0
  592. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/rename_windows.go +55 -0
  593. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sock.go +186 -0
  594. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sock_supported.go +76 -0
  595. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sock_unix.go +48 -0
  596. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sock_unsupported.go +79 -0
  597. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sock_windows.go +80 -0
  598. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/stat.go +16 -0
  599. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/stat_supported.go +40 -0
  600. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/stat_unsupported.go +40 -0
  601. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/stat_windows.go +118 -0
  602. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sync.go +13 -0
  603. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sync_windows.go +20 -0
  604. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/syscall6_darwin.go +13 -0
  605. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/sysfs.go +6 -0
  606. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/unlink_unix.go +17 -0
  607. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/unlink_unsupported.go +14 -0
  608. package/govendor/github.com/tetratelabs/wazero/internal/sysfs/unlink_windows.go +25 -0
  609. package/govendor/github.com/tetratelabs/wazero/internal/u32/u32.go +11 -0
  610. package/govendor/github.com/tetratelabs/wazero/internal/u64/u64.go +15 -0
  611. package/govendor/github.com/tetratelabs/wazero/internal/version/version.go +52 -0
  612. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/args.go +6 -0
  613. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/clock.go +16 -0
  614. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/environ.go +6 -0
  615. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/errno.go +314 -0
  616. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/fs.go +164 -0
  617. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/poll.go +15 -0
  618. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/proc.go +6 -0
  619. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/random.go +3 -0
  620. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/rights.go +148 -0
  621. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/sched.go +3 -0
  622. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/sock.go +71 -0
  623. package/govendor/github.com/tetratelabs/wazero/internal/wasip1/wasi.go +26 -0
  624. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/code.go +124 -0
  625. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/const_expr.go +116 -0
  626. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/custom.go +22 -0
  627. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/data.go +79 -0
  628. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/decoder.go +235 -0
  629. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/element.go +250 -0
  630. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/errors.go +11 -0
  631. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/export.go +32 -0
  632. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/function.go +56 -0
  633. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/global.go +50 -0
  634. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/header.go +9 -0
  635. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/import.go +68 -0
  636. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/limits.go +47 -0
  637. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/memory.go +42 -0
  638. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/names.go +151 -0
  639. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/section.go +309 -0
  640. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/table.go +79 -0
  641. package/govendor/github.com/tetratelabs/wazero/internal/wasm/binary/value.go +97 -0
  642. package/govendor/github.com/tetratelabs/wazero/internal/wasm/const_expr.go +259 -0
  643. package/govendor/github.com/tetratelabs/wazero/internal/wasm/counts.go +53 -0
  644. package/govendor/github.com/tetratelabs/wazero/internal/wasm/engine.go +76 -0
  645. package/govendor/github.com/tetratelabs/wazero/internal/wasm/exception.go +9 -0
  646. package/govendor/github.com/tetratelabs/wazero/internal/wasm/func_validation.go +2804 -0
  647. package/govendor/github.com/tetratelabs/wazero/internal/wasm/function_definition.go +210 -0
  648. package/govendor/github.com/tetratelabs/wazero/internal/wasm/global.go +55 -0
  649. package/govendor/github.com/tetratelabs/wazero/internal/wasm/gofunc.go +279 -0
  650. package/govendor/github.com/tetratelabs/wazero/internal/wasm/host.go +179 -0
  651. package/govendor/github.com/tetratelabs/wazero/internal/wasm/instruction.go +1962 -0
  652. package/govendor/github.com/tetratelabs/wazero/internal/wasm/memory.go +475 -0
  653. package/govendor/github.com/tetratelabs/wazero/internal/wasm/memory_definition.go +128 -0
  654. package/govendor/github.com/tetratelabs/wazero/internal/wasm/module.go +1359 -0
  655. package/govendor/github.com/tetratelabs/wazero/internal/wasm/module_instance.go +251 -0
  656. package/govendor/github.com/tetratelabs/wazero/internal/wasm/module_instance_lookup.go +73 -0
  657. package/govendor/github.com/tetratelabs/wazero/internal/wasm/store.go +726 -0
  658. package/govendor/github.com/tetratelabs/wazero/internal/wasm/store_module_list.go +95 -0
  659. package/govendor/github.com/tetratelabs/wazero/internal/wasm/table.go +321 -0
  660. package/govendor/github.com/tetratelabs/wazero/internal/wasmdebug/debug.go +170 -0
  661. package/govendor/github.com/tetratelabs/wazero/internal/wasmdebug/dwarf.go +225 -0
  662. package/govendor/github.com/tetratelabs/wazero/internal/wasmruntime/errors.go +54 -0
  663. package/govendor/github.com/tetratelabs/wazero/netlify.toml +15 -0
  664. package/govendor/github.com/tetratelabs/wazero/runtime.go +399 -0
  665. package/govendor/github.com/tetratelabs/wazero/sys/clock.go +26 -0
  666. package/govendor/github.com/tetratelabs/wazero/sys/error.go +83 -0
  667. package/govendor/github.com/tetratelabs/wazero/sys/stat.go +105 -0
  668. package/govendor/github.com/tetratelabs/wazero/sys/stat_bsd.go +29 -0
  669. package/govendor/github.com/tetratelabs/wazero/sys/stat_posix.go +29 -0
  670. package/govendor/github.com/tetratelabs/wazero/sys/stat_unsupported.go +14 -0
  671. package/govendor/github.com/tetratelabs/wazero/sys/stat_windows.go +24 -0
  672. package/govendor/golang.org/x/crypto/LICENSE +27 -0
  673. package/govendor/golang.org/x/crypto/PATENTS +22 -0
  674. package/govendor/golang.org/x/crypto/cryptobyte/asn1/asn1.go +46 -0
  675. package/govendor/golang.org/x/crypto/cryptobyte/asn1.go +825 -0
  676. package/govendor/golang.org/x/crypto/cryptobyte/builder.go +350 -0
  677. package/govendor/golang.org/x/crypto/cryptobyte/string.go +183 -0
  678. package/govendor/golang.org/x/crypto/go.mod +3 -0
  679. package/govendor/golang.org/x/crypto/pbkdf2/pbkdf2.go +30 -0
  680. package/govendor/golang.org/x/net/LICENSE +27 -0
  681. package/govendor/golang.org/x/net/PATENTS +22 -0
  682. package/govendor/golang.org/x/net/dns/dnsmessage/message.go +2733 -0
  683. package/govendor/golang.org/x/net/dns/dnsmessage/svcb.go +333 -0
  684. package/govendor/golang.org/x/net/go.mod +3 -0
  685. package/govendor/golang.org/x/net/http/httpguts/guts.go +50 -0
  686. package/govendor/golang.org/x/net/http/httpguts/httplex.go +347 -0
  687. package/govendor/golang.org/x/net/http2/README.md +19 -0
  688. package/govendor/golang.org/x/net/http2/ascii.go +65 -0
  689. package/govendor/golang.org/x/net/http2/ciphers.go +641 -0
  690. package/govendor/golang.org/x/net/http2/client_conn_pool.go +301 -0
  691. package/govendor/golang.org/x/net/http2/client_priority_go126.go +20 -0
  692. package/govendor/golang.org/x/net/http2/client_priority_go127.go +13 -0
  693. package/govendor/golang.org/x/net/http2/clientconn.go +57 -0
  694. package/govendor/golang.org/x/net/http2/config.go +171 -0
  695. package/govendor/golang.org/x/net/http2/config_go125.go +15 -0
  696. package/govendor/golang.org/x/net/http2/config_go126.go +15 -0
  697. package/govendor/golang.org/x/net/http2/databuffer.go +146 -0
  698. package/govendor/golang.org/x/net/http2/errors.go +145 -0
  699. package/govendor/golang.org/x/net/http2/flow.go +175 -0
  700. package/govendor/golang.org/x/net/http2/frame.go +1887 -0
  701. package/govendor/golang.org/x/net/http2/gotrack.go +181 -0
  702. package/govendor/golang.org/x/net/http2/hpack/encode.go +244 -0
  703. package/govendor/golang.org/x/net/http2/hpack/hpack.go +522 -0
  704. package/govendor/golang.org/x/net/http2/hpack/huffman.go +226 -0
  705. package/govendor/golang.org/x/net/http2/hpack/static_table.go +188 -0
  706. package/govendor/golang.org/x/net/http2/hpack/tables.go +426 -0
  707. package/govendor/golang.org/x/net/http2/http2.go +415 -0
  708. package/govendor/golang.org/x/net/http2/pipe.go +184 -0
  709. package/govendor/golang.org/x/net/http2/server.go +3239 -0
  710. package/govendor/golang.org/x/net/http2/server_common.go +268 -0
  711. package/govendor/golang.org/x/net/http2/server_wrap.go +217 -0
  712. package/govendor/golang.org/x/net/http2/transport.go +3084 -0
  713. package/govendor/golang.org/x/net/http2/transport_common.go +516 -0
  714. package/govendor/golang.org/x/net/http2/transport_wrap.go +583 -0
  715. package/govendor/golang.org/x/net/http2/unencrypted.go +32 -0
  716. package/govendor/golang.org/x/net/http2/write.go +381 -0
  717. package/govendor/golang.org/x/net/http2/writesched.go +253 -0
  718. package/govendor/golang.org/x/net/http2/writesched_common.go +90 -0
  719. package/govendor/golang.org/x/net/http2/writesched_priority_rfc7540.go +420 -0
  720. package/govendor/golang.org/x/net/http2/writesched_priority_rfc9218.go +226 -0
  721. package/govendor/golang.org/x/net/http2/writesched_random.go +81 -0
  722. package/govendor/golang.org/x/net/http2/writesched_roundrobin.go +121 -0
  723. package/govendor/golang.org/x/net/idna/idna.go +884 -0
  724. package/govendor/golang.org/x/net/idna/punycode.go +220 -0
  725. package/govendor/golang.org/x/net/idna/tables15.0.0.go +5144 -0
  726. package/govendor/golang.org/x/net/idna/tables17.0.0.go +5302 -0
  727. package/govendor/golang.org/x/net/idna/trie.go +51 -0
  728. package/govendor/golang.org/x/net/idna/trieval.go +119 -0
  729. package/govendor/golang.org/x/net/internal/httpcommon/README.md +7 -0
  730. package/govendor/golang.org/x/net/internal/httpcommon/ascii.go +53 -0
  731. package/govendor/golang.org/x/net/internal/httpcommon/gzip.go +132 -0
  732. package/govendor/golang.org/x/net/internal/httpcommon/headermap.go +115 -0
  733. package/govendor/golang.org/x/net/internal/httpcommon/request.go +503 -0
  734. package/govendor/golang.org/x/net/internal/httpsfv/httpsfv.go +665 -0
  735. package/govendor/golang.org/x/sys/cpu/asm_aix_ppc64.s +17 -0
  736. package/govendor/golang.org/x/sys/cpu/asm_darwin_arm64_gc.s +12 -0
  737. package/govendor/golang.org/x/sys/cpu/asm_darwin_x86_gc.s +17 -0
  738. package/govendor/golang.org/x/sys/cpu/byteorder.go +66 -0
  739. package/govendor/golang.org/x/sys/cpu/cpu.go +357 -0
  740. package/govendor/golang.org/x/sys/cpu/cpu_aix.go +33 -0
  741. package/govendor/golang.org/x/sys/cpu/cpu_arm.go +73 -0
  742. package/govendor/golang.org/x/sys/cpu/cpu_arm64.go +191 -0
  743. package/govendor/golang.org/x/sys/cpu/cpu_arm64.s +35 -0
  744. package/govendor/golang.org/x/sys/cpu/cpu_darwin_arm64.go +67 -0
  745. package/govendor/golang.org/x/sys/cpu/cpu_darwin_arm64_other.go +31 -0
  746. package/govendor/golang.org/x/sys/cpu/cpu_darwin_x86.go +61 -0
  747. package/govendor/golang.org/x/sys/cpu/cpu_gc_arm64.go +12 -0
  748. package/govendor/golang.org/x/sys/cpu/cpu_gc_riscv64.go +11 -0
  749. package/govendor/golang.org/x/sys/cpu/cpu_gc_s390x.go +21 -0
  750. package/govendor/golang.org/x/sys/cpu/cpu_gc_x86.go +15 -0
  751. package/govendor/golang.org/x/sys/cpu/cpu_gc_x86.s +26 -0
  752. package/govendor/golang.org/x/sys/cpu/cpu_gccgo_arm64.go +12 -0
  753. package/govendor/golang.org/x/sys/cpu/cpu_gccgo_s390x.go +22 -0
  754. package/govendor/golang.org/x/sys/cpu/cpu_gccgo_x86.c +37 -0
  755. package/govendor/golang.org/x/sys/cpu/cpu_gccgo_x86.go +25 -0
  756. package/govendor/golang.org/x/sys/cpu/cpu_linux.go +15 -0
  757. package/govendor/golang.org/x/sys/cpu/cpu_linux_arm.go +39 -0
  758. package/govendor/golang.org/x/sys/cpu/cpu_linux_arm64.go +120 -0
  759. package/govendor/golang.org/x/sys/cpu/cpu_linux_loong64.go +22 -0
  760. package/govendor/golang.org/x/sys/cpu/cpu_linux_mips64x.go +22 -0
  761. package/govendor/golang.org/x/sys/cpu/cpu_linux_noinit.go +9 -0
  762. package/govendor/golang.org/x/sys/cpu/cpu_linux_ppc64x.go +34 -0
  763. package/govendor/golang.org/x/sys/cpu/cpu_linux_riscv64.go +173 -0
  764. package/govendor/golang.org/x/sys/cpu/cpu_linux_s390x.go +40 -0
  765. package/govendor/golang.org/x/sys/cpu/cpu_loong64.go +62 -0
  766. package/govendor/golang.org/x/sys/cpu/cpu_loong64.s +13 -0
  767. package/govendor/golang.org/x/sys/cpu/cpu_mips64x.go +15 -0
  768. package/govendor/golang.org/x/sys/cpu/cpu_mipsx.go +11 -0
  769. package/govendor/golang.org/x/sys/cpu/cpu_netbsd_amd64.go +47 -0
  770. package/govendor/golang.org/x/sys/cpu/cpu_netbsd_arm64.go +173 -0
  771. package/govendor/golang.org/x/sys/cpu/cpu_openbsd_arm64.go +65 -0
  772. package/govendor/golang.org/x/sys/cpu/cpu_openbsd_arm64.s +11 -0
  773. package/govendor/golang.org/x/sys/cpu/cpu_other_arm.go +9 -0
  774. package/govendor/golang.org/x/sys/cpu/cpu_other_arm64.go +11 -0
  775. package/govendor/golang.org/x/sys/cpu/cpu_other_mips64x.go +11 -0
  776. package/govendor/golang.org/x/sys/cpu/cpu_other_ppc64x.go +12 -0
  777. package/govendor/golang.org/x/sys/cpu/cpu_other_riscv64.go +11 -0
  778. package/govendor/golang.org/x/sys/cpu/cpu_other_x86.go +11 -0
  779. package/govendor/golang.org/x/sys/cpu/cpu_ppc64x.go +16 -0
  780. package/govendor/golang.org/x/sys/cpu/cpu_riscv64.go +33 -0
  781. package/govendor/golang.org/x/sys/cpu/cpu_riscv64.s +17 -0
  782. package/govendor/golang.org/x/sys/cpu/cpu_s390x.go +172 -0
  783. package/govendor/golang.org/x/sys/cpu/cpu_s390x.s +57 -0
  784. package/govendor/golang.org/x/sys/cpu/cpu_sparc64.go +12 -0
  785. package/govendor/golang.org/x/sys/cpu/cpu_wasm.go +17 -0
  786. package/govendor/golang.org/x/sys/cpu/cpu_windows.go +26 -0
  787. package/govendor/golang.org/x/sys/cpu/cpu_windows_arm64.go +38 -0
  788. package/govendor/golang.org/x/sys/cpu/cpu_x86.go +259 -0
  789. package/govendor/golang.org/x/sys/cpu/cpu_zos.go +10 -0
  790. package/govendor/golang.org/x/sys/cpu/cpu_zos_s390x.go +25 -0
  791. package/govendor/golang.org/x/sys/cpu/endian_big.go +10 -0
  792. package/govendor/golang.org/x/sys/cpu/endian_little.go +10 -0
  793. package/govendor/golang.org/x/sys/cpu/hwcap_linux.go +71 -0
  794. package/govendor/golang.org/x/sys/cpu/parse.go +55 -0
  795. package/govendor/golang.org/x/sys/cpu/proc_cpuinfo_linux.go +53 -0
  796. package/govendor/golang.org/x/sys/cpu/runtime_auxv.go +16 -0
  797. package/govendor/golang.org/x/sys/cpu/runtime_auxv_go121.go +18 -0
  798. package/govendor/golang.org/x/sys/cpu/syscall_aix_gccgo.go +26 -0
  799. package/govendor/golang.org/x/sys/cpu/syscall_aix_ppc64_gc.go +35 -0
  800. package/govendor/golang.org/x/sys/cpu/syscall_darwin_arm64_gc.go +54 -0
  801. package/govendor/golang.org/x/sys/cpu/syscall_darwin_x86_gc.go +98 -0
  802. package/govendor/golang.org/x/sys/cpu/zcpu_windows.go +48 -0
  803. package/govendor/golang.org/x/sys/unix/asm_linux_ppc64x.s +20 -0
  804. package/govendor/golang.org/x/sys/unix/asm_linux_sparc64.s +48 -0
  805. package/govendor/golang.org/x/sys/unix/asm_zos_s390x.s +4 -186
  806. package/govendor/golang.org/x/sys/unix/bpxsvc_zos.s +9 -9
  807. package/govendor/golang.org/x/sys/unix/fcntl_darwin.go +2 -2
  808. package/govendor/golang.org/x/sys/unix/mkerrors.sh +1 -1
  809. package/govendor/golang.org/x/sys/unix/ptrace_zos.go +537 -0
  810. package/govendor/golang.org/x/sys/unix/ptrace_zos_singlestep.go +425 -0
  811. package/govendor/golang.org/x/sys/unix/syscall_darwin.go +1 -0
  812. package/govendor/golang.org/x/sys/unix/syscall_freebsd.go +9 -0
  813. package/govendor/golang.org/x/sys/unix/syscall_linux.go +20 -1
  814. package/govendor/golang.org/x/sys/unix/syscall_linux_sparc64.go +3 -3
  815. package/govendor/golang.org/x/sys/unix/syscall_netbsd.go +9 -0
  816. package/govendor/golang.org/x/sys/unix/syscall_unix_gc.go +1 -1
  817. package/govendor/golang.org/x/sys/unix/syscall_zos_s390x.go +0 -4
  818. package/govendor/golang.org/x/sys/unix/xattr_bsd.go +12 -12
  819. package/govendor/golang.org/x/sys/unix/zerrors_darwin_amd64.go +6 -0
  820. package/govendor/golang.org/x/sys/unix/zerrors_darwin_arm64.go +6 -0
  821. package/govendor/golang.org/x/sys/unix/zerrors_linux.go +32 -0
  822. package/govendor/golang.org/x/sys/unix/zerrors_linux_386.go +2 -0
  823. package/govendor/golang.org/x/sys/unix/zerrors_linux_amd64.go +2 -0
  824. package/govendor/golang.org/x/sys/unix/zerrors_linux_arm.go +2 -0
  825. package/govendor/golang.org/x/sys/unix/zerrors_linux_arm64.go +2 -0
  826. package/govendor/golang.org/x/sys/unix/zerrors_linux_loong64.go +2 -0
  827. package/govendor/golang.org/x/sys/unix/zerrors_linux_mips.go +2 -0
  828. package/govendor/golang.org/x/sys/unix/zerrors_linux_mips64.go +2 -0
  829. package/govendor/golang.org/x/sys/unix/zerrors_linux_mips64le.go +2 -0
  830. package/govendor/golang.org/x/sys/unix/zerrors_linux_mipsle.go +2 -0
  831. package/govendor/golang.org/x/sys/unix/zerrors_linux_ppc.go +2 -0
  832. package/govendor/golang.org/x/sys/unix/zerrors_linux_ppc64.go +2 -0
  833. package/govendor/golang.org/x/sys/unix/zerrors_linux_ppc64le.go +2 -0
  834. package/govendor/golang.org/x/sys/unix/zerrors_linux_riscv64.go +2 -0
  835. package/govendor/golang.org/x/sys/unix/zerrors_linux_s390x.go +2 -0
  836. package/govendor/golang.org/x/sys/unix/zerrors_linux_sparc64.go +2 -0
  837. package/govendor/golang.org/x/sys/unix/zsyscall_darwin_amd64.go +11 -0
  838. package/govendor/golang.org/x/sys/unix/zsyscall_darwin_arm64.go +11 -0
  839. package/govendor/golang.org/x/sys/unix/zsyscall_freebsd_386.go +159 -0
  840. package/govendor/golang.org/x/sys/unix/zsyscall_freebsd_amd64.go +159 -0
  841. package/govendor/golang.org/x/sys/unix/zsyscall_freebsd_arm.go +159 -0
  842. package/govendor/golang.org/x/sys/unix/zsyscall_freebsd_arm64.go +159 -0
  843. package/govendor/golang.org/x/sys/unix/zsyscall_freebsd_riscv64.go +159 -0
  844. package/govendor/golang.org/x/sys/unix/zsyscall_linux.go +28 -1
  845. package/govendor/golang.org/x/sys/unix/zsyscall_linux_sparc64.go +3 -3
  846. package/govendor/golang.org/x/sys/unix/zsyscall_netbsd_386.go +159 -0
  847. package/govendor/golang.org/x/sys/unix/zsyscall_netbsd_amd64.go +159 -0
  848. package/govendor/golang.org/x/sys/unix/zsyscall_netbsd_arm.go +159 -0
  849. package/govendor/golang.org/x/sys/unix/zsyscall_netbsd_arm64.go +159 -0
  850. package/govendor/golang.org/x/sys/unix/zsysnum_zos_s390x.go +13 -0
  851. package/govendor/golang.org/x/sys/unix/ztypes_linux.go +65 -36
  852. package/govendor/golang.org/x/sys/unix/ztypes_linux_386.go +6 -0
  853. package/govendor/golang.org/x/sys/unix/ztypes_linux_amd64.go +7 -0
  854. package/govendor/golang.org/x/sys/unix/ztypes_linux_arm.go +6 -0
  855. package/govendor/golang.org/x/sys/unix/ztypes_linux_arm64.go +7 -0
  856. package/govendor/golang.org/x/sys/unix/ztypes_linux_loong64.go +7 -0
  857. package/govendor/golang.org/x/sys/unix/ztypes_linux_mips.go +6 -0
  858. package/govendor/golang.org/x/sys/unix/ztypes_linux_mips64.go +7 -0
  859. package/govendor/golang.org/x/sys/unix/ztypes_linux_mips64le.go +7 -0
  860. package/govendor/golang.org/x/sys/unix/ztypes_linux_mipsle.go +6 -0
  861. package/govendor/golang.org/x/sys/unix/ztypes_linux_ppc.go +6 -0
  862. package/govendor/golang.org/x/sys/unix/ztypes_linux_ppc64.go +7 -0
  863. package/govendor/golang.org/x/sys/unix/ztypes_linux_ppc64le.go +7 -0
  864. package/govendor/golang.org/x/sys/unix/ztypes_linux_riscv64.go +7 -0
  865. package/govendor/golang.org/x/sys/unix/ztypes_linux_s390x.go +7 -0
  866. package/govendor/golang.org/x/sys/unix/ztypes_linux_sparc64.go +10 -5
  867. package/govendor/golang.org/x/sys/unix/ztypes_zos_s390x.go +78 -0
  868. package/govendor/golang.org/x/text/.gitattributes +10 -0
  869. package/govendor/golang.org/x/text/CONTRIBUTING.md +26 -0
  870. package/govendor/golang.org/x/text/LICENSE +27 -0
  871. package/govendor/golang.org/x/text/PATENTS +22 -0
  872. package/govendor/golang.org/x/text/README.md +81 -0
  873. package/govendor/golang.org/x/text/cases/cases.go +162 -0
  874. package/govendor/golang.org/x/text/cases/context.go +376 -0
  875. package/govendor/golang.org/x/text/cases/fold.go +34 -0
  876. package/govendor/golang.org/x/text/cases/icu.go +61 -0
  877. package/govendor/golang.org/x/text/cases/info.go +82 -0
  878. package/govendor/golang.org/x/text/cases/map.go +816 -0
  879. package/govendor/golang.org/x/text/cases/tables15.0.0.go +2527 -0
  880. package/govendor/golang.org/x/text/cases/tables17.0.0.go +2642 -0
  881. package/govendor/golang.org/x/text/cases/trieval.go +217 -0
  882. package/govendor/golang.org/x/text/codereview.cfg +1 -0
  883. package/govendor/golang.org/x/text/collate/collate.go +402 -0
  884. package/govendor/golang.org/x/text/collate/index.go +32 -0
  885. package/govendor/golang.org/x/text/collate/option.go +239 -0
  886. package/govendor/golang.org/x/text/collate/sort.go +81 -0
  887. package/govendor/golang.org/x/text/collate/tables.go +73789 -0
  888. package/govendor/golang.org/x/text/currency/common.go +67 -0
  889. package/govendor/golang.org/x/text/currency/currency.go +185 -0
  890. package/govendor/golang.org/x/text/currency/format.go +220 -0
  891. package/govendor/golang.org/x/text/currency/query.go +152 -0
  892. package/govendor/golang.org/x/text/currency/tables.go +2629 -0
  893. package/govendor/golang.org/x/text/doc.go +16 -0
  894. package/govendor/golang.org/x/text/feature/plural/common.go +70 -0
  895. package/govendor/golang.org/x/text/feature/plural/message.go +244 -0
  896. package/govendor/golang.org/x/text/feature/plural/plural.go +262 -0
  897. package/govendor/golang.org/x/text/feature/plural/tables.go +552 -0
  898. package/govendor/golang.org/x/text/go.mod +3 -0
  899. package/govendor/golang.org/x/text/internal/catmsg/catmsg.go +417 -0
  900. package/govendor/golang.org/x/text/internal/catmsg/codec.go +407 -0
  901. package/govendor/golang.org/x/text/internal/catmsg/varint.go +62 -0
  902. package/govendor/golang.org/x/text/internal/colltab/collelem.go +374 -0
  903. package/govendor/golang.org/x/text/internal/colltab/colltab.go +105 -0
  904. package/govendor/golang.org/x/text/internal/colltab/contract.go +145 -0
  905. package/govendor/golang.org/x/text/internal/colltab/iter.go +178 -0
  906. package/govendor/golang.org/x/text/internal/colltab/numeric.go +236 -0
  907. package/govendor/golang.org/x/text/internal/colltab/table.go +275 -0
  908. package/govendor/golang.org/x/text/internal/colltab/trie.go +159 -0
  909. package/govendor/golang.org/x/text/internal/colltab/weighter.go +31 -0
  910. package/govendor/golang.org/x/text/internal/format/format.go +41 -0
  911. package/govendor/golang.org/x/text/internal/format/parser.go +358 -0
  912. package/govendor/golang.org/x/text/internal/internal.go +49 -0
  913. package/govendor/golang.org/x/text/internal/language/common.go +16 -0
  914. package/govendor/golang.org/x/text/internal/language/compact/compact.go +61 -0
  915. package/govendor/golang.org/x/text/internal/language/compact/language.go +260 -0
  916. package/govendor/golang.org/x/text/internal/language/compact/parents.go +120 -0
  917. package/govendor/golang.org/x/text/internal/language/compact/tables.go +1015 -0
  918. package/govendor/golang.org/x/text/internal/language/compact/tags.go +91 -0
  919. package/govendor/golang.org/x/text/internal/language/compact.go +29 -0
  920. package/govendor/golang.org/x/text/internal/language/compose.go +167 -0
  921. package/govendor/golang.org/x/text/internal/language/coverage.go +28 -0
  922. package/govendor/golang.org/x/text/internal/language/language.go +627 -0
  923. package/govendor/golang.org/x/text/internal/language/lookup.go +412 -0
  924. package/govendor/golang.org/x/text/internal/language/match.go +226 -0
  925. package/govendor/golang.org/x/text/internal/language/parse.go +608 -0
  926. package/govendor/golang.org/x/text/internal/language/tables.go +3494 -0
  927. package/govendor/golang.org/x/text/internal/language/tags.go +48 -0
  928. package/govendor/golang.org/x/text/internal/match.go +67 -0
  929. package/govendor/golang.org/x/text/internal/number/common.go +55 -0
  930. package/govendor/golang.org/x/text/internal/number/decimal.go +500 -0
  931. package/govendor/golang.org/x/text/internal/number/format.go +533 -0
  932. package/govendor/golang.org/x/text/internal/number/number.go +152 -0
  933. package/govendor/golang.org/x/text/internal/number/pattern.go +485 -0
  934. package/govendor/golang.org/x/text/internal/number/roundingmode_string.go +30 -0
  935. package/govendor/golang.org/x/text/internal/number/tables.go +1219 -0
  936. package/govendor/golang.org/x/text/internal/stringset/set.go +86 -0
  937. package/govendor/golang.org/x/text/internal/tag/tag.go +100 -0
  938. package/govendor/golang.org/x/text/language/coverage.go +187 -0
  939. package/govendor/golang.org/x/text/language/display/dict.go +92 -0
  940. package/govendor/golang.org/x/text/language/display/display.go +420 -0
  941. package/govendor/golang.org/x/text/language/display/lookup.go +253 -0
  942. package/govendor/golang.org/x/text/language/display/tables.go +53114 -0
  943. package/govendor/golang.org/x/text/language/doc.go +98 -0
  944. package/govendor/golang.org/x/text/language/language.go +605 -0
  945. package/govendor/golang.org/x/text/language/match.go +735 -0
  946. package/govendor/golang.org/x/text/language/parse.go +258 -0
  947. package/govendor/golang.org/x/text/language/tables.go +298 -0
  948. package/govendor/golang.org/x/text/language/tags.go +145 -0
  949. package/govendor/golang.org/x/text/message/catalog/catalog.go +365 -0
  950. package/govendor/golang.org/x/text/message/catalog/dict.go +133 -0
  951. package/govendor/golang.org/x/text/secure/bidirule/bidirule.go +346 -0
  952. package/govendor/golang.org/x/text/transform/transform.go +709 -0
  953. package/govendor/golang.org/x/text/unicode/bidi/bidi.go +359 -0
  954. package/govendor/golang.org/x/text/unicode/bidi/bracket.go +335 -0
  955. package/govendor/golang.org/x/text/unicode/bidi/core.go +1050 -0
  956. package/govendor/golang.org/x/text/unicode/bidi/prop.go +206 -0
  957. package/govendor/golang.org/x/text/unicode/bidi/tables15.0.0.go +2042 -0
  958. package/govendor/golang.org/x/text/unicode/bidi/tables17.0.0.go +2135 -0
  959. package/govendor/golang.org/x/text/unicode/bidi/trieval.go +48 -0
  960. package/govendor/golang.org/x/text/unicode/norm/composition.go +524 -0
  961. package/govendor/golang.org/x/text/unicode/norm/forminfo.go +296 -0
  962. package/govendor/golang.org/x/text/unicode/norm/input.go +109 -0
  963. package/govendor/golang.org/x/text/unicode/norm/iter.go +454 -0
  964. package/govendor/golang.org/x/text/unicode/norm/normalize.go +613 -0
  965. package/govendor/golang.org/x/text/unicode/norm/readwriter.go +125 -0
  966. package/govendor/golang.org/x/text/unicode/norm/tables15.0.0.go +7907 -0
  967. package/govendor/golang.org/x/text/unicode/norm/tables17.0.0.go +8104 -0
  968. package/govendor/golang.org/x/text/unicode/norm/transform.go +89 -0
  969. package/govendor/golang.org/x/text/unicode/norm/trie.go +54 -0
  970. package/govendor/manifest.txt +11 -2
  971. package/package.json +2 -1
  972. package/performance/README.md +87 -35
  973. package/performance/arr-for-of.ts +29 -0
  974. package/performance/arr-push-local.ts +39 -0
  975. package/performance/arr-slice-concat.ts +24 -0
  976. package/performance/async-promise-all.ts +38 -0
  977. package/performance/bigint-arith.ts +36 -0
  978. package/performance/buf-encode.ts +29 -0
  979. package/performance/class-accessors.ts +48 -0
  980. package/performance/date-format.ts +18 -0
  981. package/performance/fn-rest-spread.ts +43 -0
  982. package/performance/gen-next.ts +32 -0
  983. package/performance/iter-helpers.ts +38 -0
  984. package/performance/json-any.ts +30 -0
  985. package/performance/map-iterate.ts +26 -0
  986. package/performance/map-number-keys.ts +37 -0
  987. package/performance/num-hash-imul.ts +36 -0
  988. package/performance/obj-keys-entries.ts +44 -0
  989. package/performance/obj-optional-chain.ts +42 -0
  990. package/performance/obj-record-dict.ts +24 -0
  991. package/performance/obj-spread-destructure.ts +40 -0
  992. package/performance/regex-replace-fn.ts +24 -0
  993. package/performance/str-methods.ts +24 -0
  994. package/performance/str-switch-compare.ts +50 -0
  995. package/performance/str-unicode.ts +25 -0
  996. package/performance/typed-array.ts +30 -0
  997. package/performance/union-typeof.ts +40 -0
  998. package/performance/wasm-call.ts +63 -0
  999. package/tsparser/go.mod +1 -1
  1000. package/tsparser/go.sum +2 -2
  1001. package/types/typenative-npm.d.ts +836 -69
  1002. package/types/typenative.d.ts +1224 -23
  1003. package/govendor/golang.org/x/sys/unix/syscall_unix_gc_ppc64x.go +0 -22
  1004. package/govendor/golang.org/x/sys/windows/types_windows_arm.go +0 -35
@@ -0,0 +1,1577 @@
1
+ # Notable rationale of wazero
2
+
3
+ ## Zero dependencies
4
+
5
+ Wazero has zero dependencies to differentiate itself from other runtimes which
6
+ have heavy impact usually due to CGO. By avoiding CGO, wazero avoids
7
+ prerequisites such as shared libraries or libc, and lets users keep features
8
+ like cross compilation.
9
+
10
+ Avoiding most `go.mod` dependencies reduces interference on Go version support,
11
+ and size of a statically compiled binary. However, doing so brings some
12
+ responsibility into the project.
13
+
14
+ Go's native platform support is good: we don't need platform-specific code to
15
+ get monotonic time, nor do we need much work to implement certain features
16
+ needed by our compiler such as `mmap`. That said, Go does not support all
17
+ common operating systems to the same degree.
18
+
19
+ The general tradeoff the project takes from a strict dependency policy is more
20
+ explicit support of platforms (in the compiler runtime), as well a larger and
21
+ more technically difficult codebase.
22
+
23
+ ### Why do we use CGO to implement system calls on darwin?
24
+
25
+ wazero is dependency and CGO free by design. In some cases, we have code that
26
+ can optionally use CGO, but retain a fallback for when that's disabled. The only
27
+ operating system (`GOOS`) we use CGO by default in is `darwin`.
28
+
29
+ Unlike other operating systems, regardless of `CGO_ENABLED`, Go always uses
30
+ "CGO" mechanisms in the runtime layer of `darwin`. This is explained in
31
+ [Statically linked binaries on Mac OS X](https://developer.apple.com/library/archive/qa/qa1118/_index.html#//apple_ref/doc/uid/DTS10001666):
32
+
33
+ > Apple does not support statically linked binaries on Mac OS X. A statically
34
+ > linked binary assumes binary compatibility at the kernel system call
35
+ > interface, and we do not make any guarantees on that front. Rather, we strive
36
+ > to ensure binary compatibility in each dynamically linked system library and
37
+ > framework.
38
+
39
+ This plays to our advantage for system calls that aren't yet exposed in the Go
40
+ standard library, notably `futimens` for nanosecond-precision timestamp
41
+ manipulation.
42
+
43
+ ### Why x/sys
44
+
45
+ The [x/sys library](https://pkg.go.dev/golang.org/x/sys/unix) is currently
46
+ our only `go.mod` dependency.
47
+
48
+ That module is maintained by the Go authors, and covers OSes that the syscall
49
+ package neglects.
50
+
51
+ After [heavy consideration](https://github.com/wazero/wazero/issues/2434) we
52
+ decided to add it as a dependency.
53
+
54
+ Using was shown to improve the experience of using wazero on older,
55
+ or less common, OSes without increasing the maintenance work, or creating
56
+ deployment issues for users of wazero.
57
+
58
+ ## Project structure
59
+
60
+ wazero uses internal packages extensively to balance API compatibility desires for end users with the need to safely
61
+ share internals between compilers.
62
+
63
+ End-user packages include `wazero`, with `Config` structs, `api`, with shared types, and the built-in `wasi` library.
64
+ Everything else is internal.
65
+
66
+ We put the main program for wazero into a directory of the same name to match conventions used in `go install`,
67
+ notably the name of the folder becomes the binary name. We chose to use `cmd/wazero` as it is common practice
68
+ and less surprising than `wazero/wazero`.
69
+
70
+ ### Internal packages
71
+
72
+ Most code in wazero is internal, and it is acknowledged that this prevents external implementation of facets such as
73
+ compilers or decoding. It also prevents splitting this code into separate repositories, resulting in a larger monorepo.
74
+ This also adds work as more code needs to be centrally reviewed.
75
+
76
+ However, the alternative is neither secure nor viable. To allow external implementation would require exporting symbols
77
+ public, such as the `CodeSection`, which can easily create bugs. Moreover, there's a high drift risk for any attempt at
78
+ external implementations, compounded not just by wazero's code organization, but also the fast moving Wasm and WASI
79
+ specifications.
80
+
81
+ For example, implementing a compiler correctly requires expertise in Wasm, Golang and assembly. This requires deep
82
+ insight into how internals are meant to be structured and the various tiers of testing required for `wazero` to result
83
+ in a high quality experience. Even if someone had these skills, supporting external code would introduce variables which
84
+ are constants in the central one. Supporting an external codebase is harder on the project team, and could starve time
85
+ from the already large burden on the central codebase.
86
+
87
+ The tradeoffs of internal packages are a larger codebase and responsibility to implement all standard features. It also
88
+ implies thinking about extension more as forking is not viable for reasons above also. The primary mitigation of these
89
+ realities are friendly OSS licensing, high rigor and a collaborative spirit which aim to make contribution in the shared
90
+ codebase productive.
91
+
92
+ ### Avoiding cyclic dependencies
93
+
94
+ wazero shares constants and interfaces with internal code by a sharing pattern described below:
95
+ * shared interfaces and constants go in one package under root: `api`.
96
+ * user APIs and structs depend on `api` and go into the root package `wazero`.
97
+ * e.g. `InstantiateModule` -> `/wasm.go` depends on the type `api.Module`.
98
+ * implementation code can also depend on `api` in a corresponding package under `/internal`.
99
+ * Ex package `wasm` -> `/internal/wasm/*.go` and can depend on the type `api.Module`.
100
+
101
+ The above guarantees no cyclic dependencies at the cost of having to re-define symbols that exist in both packages.
102
+ For example, if `wasm.Store` is a type the user needs access to, it is narrowed by a cover type in the `wazero`:
103
+
104
+ ```go
105
+ type runtime struct {
106
+ s *wasm.Store
107
+ }
108
+ ```
109
+
110
+ This is not as bad as it sounds as mutations are only available via configuration. This means exported functions are
111
+ limited to only a few functions.
112
+
113
+ ### Avoiding security bugs
114
+
115
+ In order to avoid security flaws such as code insertion, nothing in the public API is permitted to write directly to any
116
+ mutable symbol in the internal package. For example, the package `api` is shared with internal code. To ensure
117
+ immutability, the `api` package cannot contain any mutable public symbol, such as a slice or a struct with an exported
118
+ field.
119
+
120
+ In practice, this means shared functionality like memory mutation need to be implemented by interfaces.
121
+
122
+ Here are some examples:
123
+ * `api.Memory` protects access by exposing functions like `WriteFloat64Le` instead of exporting a buffer (`[]byte`).
124
+ * There is no exported symbol for the `[]byte` representing the `CodeSection`
125
+
126
+ Besides security, this practice prevents other bugs and allows centralization of validation logic such as decoding Wasm.
127
+
128
+ ## API Design
129
+
130
+ ### Why is `context.Context` inconsistent?
131
+
132
+ It may seem strange that only certain API have an initial `context.Context`
133
+ parameter. We originally had a `context.Context` for anything that might be
134
+ traced, but it turned out to be only useful for lifecycle and host functions.
135
+
136
+ For instruction-scoped aspects like memory updates, a context parameter is too
137
+ fine-grained and also invisible in practice. For example, most users will use
138
+ the compiler engine, and its memory, global or table access will never use go's
139
+ context.
140
+
141
+ ### Why does `api.ValueType` map to uint64?
142
+
143
+ WebAssembly allows functions to be defined either by the guest or the host,
144
+ with signatures expressed as WebAssembly types. For example, `i32` is a 32-bit
145
+ type which might be interpreted as signed. Function signatures can have zero or
146
+ more parameters or results even if WebAssembly 1.0 allows up to one result.
147
+
148
+ The guest can export functions, so that the host can call it. In the case of
149
+ wazero, the host is Go and an exported function can be called via
150
+ `api.Function`. `api.Function` allows users to supply parameters and read
151
+ results as a slice of uint64. For example, if there are no results, an empty
152
+ slice is returned. The user can learn the signature via `FunctionDescription`,
153
+ which returns the `api.ValueType` corresponding to each parameter or result.
154
+ `api.ValueType` defines the mapping of WebAssembly types to `uint64` values for
155
+ reason described in this section. The special case of `v128` is also mentioned
156
+ below.
157
+
158
+ wazero maps each value type to a uint64 values because it holds the largest
159
+ type in WebAssembly 1.0 (i64). A slice allows you to express empty (e.g. a
160
+ nullary signature), for example a start function.
161
+
162
+ Here's an example of calling a function, noting this syntax works for both a
163
+ signature `(param i32 i32) (result i32)` and `(param i64 i64) (result i64)`
164
+ ```go
165
+ x, y := uint64(1), uint64(2)
166
+ results, err := mod.ExportedFunction("add").Call(ctx, x, y)
167
+ if err != nil {
168
+ log.Panicln(err)
169
+ }
170
+ fmt.Printf("%d + %d = %d\n", x, y, results[0])
171
+ ```
172
+
173
+ WebAssembly does not define an encoding strategy for host defined parameters or
174
+ results. This means the encoding rules above are defined by wazero instead. To
175
+ address this, we clarified mapping both in `api.ValueType` and added helper
176
+ functions like `api.EncodeF64`. This allows users conversions typical in Go
177
+ programming, and utilities to avoid ambiguity and edge cases around casting.
178
+
179
+ Alternatively, we could have defined a byte buffer based approach and a binary
180
+ encoding of value types in and out. For example, an empty byte slice would mean
181
+ no values, while a non-empty could use a binary encoding for supported values.
182
+ This could work, but it is more difficult for the normal case of i32 and i64.
183
+ It also shares a struggle with the current approach, which is that value types
184
+ were added after WebAssembly 1.0 and not all of them have an encoding. More on
185
+ this below.
186
+
187
+ In summary, wazero chose an approach for signature mapping because there was
188
+ none, and the one we chose biases towards simplicity with integers and handles
189
+ the rest with documentation and utilities.
190
+
191
+ #### Post 1.0 value types
192
+
193
+ Value types added after WebAssembly 1.0 stressed the current model, as some
194
+ have no encoding or are larger than 64 bits. While problematic, these value
195
+ types are not commonly used in exported (extern) functions. However, some
196
+ decisions were made and detailed below.
197
+
198
+ For example `externref` has no guest representation. wazero chose to map
199
+ references to uint64 as that's the largest value needed to encode a pointer on
200
+ supported platforms. While there are two reference types, `externref` and
201
+ `functype`, the latter is an internal detail of function tables, and the former
202
+ is rarely if ever used in function signatures as of the end of 2022.
203
+
204
+ The only value larger than 64 bits is used for SIMD (`v128`). Vectorizing via
205
+ host functions is not used as of the end of 2022. Even if it were, it would be
206
+ inefficient vs guest vectorization due to host function overhead. In other
207
+ words, the `v128` value type is unlikely to be in an exported function
208
+ signature. That it requires two uint64 values to encode is an internal detail
209
+ and not worth changing the exported function interface `api.Function`, as doing
210
+ so would break all users.
211
+
212
+ ### Interfaces, not structs
213
+
214
+ All exported types in public packages, regardless of configuration vs runtime, are interfaces. The primary benefits are
215
+ internal flexibility and avoiding people accidentally mis-initializing by instantiating the types on their own vs using
216
+ the `NewXxx` constructor functions. In other words, there's less support load when things can't be done incorrectly.
217
+
218
+ Here's an example:
219
+ ```go
220
+ rt := &RuntimeConfig{} // not initialized properly (fields are nil which shouldn't be)
221
+ rt := RuntimeConfig{} // not initialized properly (should be a pointer)
222
+ rt := wazero.NewRuntimeConfig() // initialized properly
223
+ ```
224
+
225
+ There are a few drawbacks to this, notably some work for maintainers.
226
+ * Interfaces are decoupled from the structs implementing them, which means the signature has to be repeated twice.
227
+ * Interfaces have to be documented and guarded at time of use, that 3rd party implementations aren't supported.
228
+ * As of Golang 1.21, interfaces are still [not well supported](https://github.com/golang/go/issues/5860) in godoc.
229
+
230
+ ## Config
231
+
232
+ wazero configures scopes such as Runtime and Module using `XxxConfig` types. For example, `RuntimeConfig` configures
233
+ `Runtime` and `ModuleConfig` configure `Module` (instantiation). In all cases, config types begin defaults and can be
234
+ customized by a user, e.g., selecting features or a module name override.
235
+
236
+ ### Why don't we make each configuration setting return an error?
237
+ No config types create resources that would need to be closed, nor do they return errors on use. This helps reduce
238
+ resource leaks, and makes chaining easier. It makes it possible to parse configuration (ex by parsing yaml) independent
239
+ of validating it.
240
+
241
+ Instead of:
242
+ ```
243
+ cfg, err = cfg.WithFS(fs)
244
+ if err != nil {
245
+ return err
246
+ }
247
+ cfg, err = cfg.WithName(name)
248
+ if err != nil {
249
+ return err
250
+ }
251
+ mod, err = rt.InstantiateModuleWithConfig(ctx, code, cfg)
252
+ if err != nil {
253
+ return err
254
+ }
255
+ ```
256
+
257
+ There's only one call site to handle errors:
258
+ ```
259
+ cfg = cfg.WithFS(fs).WithName(name)
260
+ mod, err = rt.InstantiateModuleWithConfig(ctx, code, cfg)
261
+ if err != nil {
262
+ return err
263
+ }
264
+ ```
265
+
266
+ This allows users one place to look for errors, and also the benefit that if anything internally opens a resource, but
267
+ errs, there's nothing they need to close. In other words, users don't need to track which resources need closing on
268
+ partial error, as that is handled internally by the only code that can read configuration fields.
269
+
270
+ ### Why are configuration immutable?
271
+ While it seems certain scopes like `Runtime` won't repeat within a process, they do, possibly in different goroutines.
272
+ For example, some users create a new runtime for each module, and some re-use the same base module configuration with
273
+ only small updates (ex the name) for each instantiation. Making configuration immutable allows them to be safely used in
274
+ any goroutine.
275
+
276
+ Since config are immutable, changes apply via return val, similar to `append` in a slice.
277
+
278
+ For example, both of these are the same sort of error:
279
+ ```go
280
+ append(slice, element) // bug as only the return value has the updated slice.
281
+ cfg.WithName(next) // bug as only the return value has the updated name.
282
+ ```
283
+
284
+ Here's an example of correct use: re-assigning explicitly or via chaining.
285
+ ```go
286
+ cfg = cfg.WithName(name) // explicit
287
+
288
+ mod, err = rt.InstantiateModuleWithConfig(ctx, code, cfg.WithName(name)) // implicit
289
+ if err != nil {
290
+ return err
291
+ }
292
+ ```
293
+
294
+ ### Why aren't configuration assigned with option types?
295
+ The option pattern is a familiar one in Go. For example, someone defines a type `func (x X) err` and uses it to update
296
+ the target. For example, you could imagine wazero could choose to make `ModuleConfig` from options vs chaining fields.
297
+
298
+ Ex instead of:
299
+ ```go
300
+ type ModuleConfig interface {
301
+ WithName(string) ModuleConfig
302
+ WithFS(fs.FS) ModuleConfig
303
+ }
304
+
305
+ struct moduleConfig {
306
+ name string
307
+ fs fs.FS
308
+ }
309
+
310
+ func (c *moduleConfig) WithName(name string) ModuleConfig {
311
+ ret := *c // copy
312
+ ret.name = name
313
+ return &ret
314
+ }
315
+
316
+ func (c *moduleConfig) WithFS(fs fs.FS) ModuleConfig {
317
+ ret := *c // copy
318
+ ret.setFS("/", fs)
319
+ return &ret
320
+ }
321
+
322
+ config := r.NewModuleConfig().WithFS(fs)
323
+ configDerived := config.WithName("name")
324
+ ```
325
+
326
+ An option function could be defined, then refactor each config method into an name prefixed option function:
327
+ ```go
328
+ type ModuleConfig interface {
329
+ }
330
+ struct moduleConfig {
331
+ name string
332
+ fs fs.FS
333
+ }
334
+
335
+ type ModuleConfigOption func(c *moduleConfig)
336
+
337
+ func ModuleConfigName(name string) ModuleConfigOption {
338
+ return func(c *moduleConfig) {
339
+ c.name = name
340
+ }
341
+ }
342
+
343
+ func ModuleConfigFS(fs fs.FS) ModuleConfigOption {
344
+ return func(c *moduleConfig) {
345
+ c.fs = fs
346
+ }
347
+ }
348
+
349
+ func (r *runtime) NewModuleConfig(opts ...ModuleConfigOption) ModuleConfig {
350
+ ret := newModuleConfig() // defaults
351
+ for _, opt := range opts {
352
+ opt(&ret.config)
353
+ }
354
+ return ret
355
+ }
356
+
357
+ func (c *moduleConfig) WithOptions(opts ...ModuleConfigOption) ModuleConfig {
358
+ ret := *c // copy base config
359
+ for _, opt := range opts {
360
+ opt(&ret.config)
361
+ }
362
+ return ret
363
+ }
364
+
365
+ config := r.NewModuleConfig(ModuleConfigFS(fs))
366
+ configDerived := config.WithOptions(ModuleConfigName("name"))
367
+ ```
368
+
369
+ wazero took the path of the former design primarily due to:
370
+ * interfaces provide natural namespaces for their methods, which is more direct than functions with name prefixes.
371
+ * parsing config into function callbacks is more direct vs parsing config into a slice of functions to do the same.
372
+ * in either case derived config is needed and the options pattern is more awkward to achieve that.
373
+
374
+ There are other reasons such as test and debug being simpler without options: the above list is constrained to conserve
375
+ space. It is accepted that the options pattern is common in Go, which is the main reason for documenting this decision.
376
+
377
+ ### Why aren't config types deeply structured?
378
+ wazero's configuration types cover the two main scopes of WebAssembly use:
379
+ * `RuntimeConfig`: This is the broadest scope, so applies also to compilation
380
+ and instantiation. e.g. This controls the WebAssembly Specification Version.
381
+ * `ModuleConfig`: This affects modules instantiated after compilation and what
382
+ resources are allowed. e.g. This defines how or if STDOUT is captured. This
383
+ also allows sub-configuration of `FSConfig`.
384
+
385
+ These default to a flat definition each, with lazy sub-configuration only after
386
+ proven to be necessary. A flat structure is easier to work with and is also
387
+ easy to discover. Unlike the option pattern described earlier, more
388
+ configuration in the interface doesn't taint the package namespace, only
389
+ `ModuleConfig`.
390
+
391
+ We default to a flat structure to encourage simplicity. If we eagerly broke out
392
+ all possible configurations into sub-types (e.g. ClockConfig), it would be hard
393
+ to notice configuration sprawl. By keeping the config flat, it is easy to see
394
+ the cognitive load we may be adding to our users.
395
+
396
+ In other words, discomfort adding more configuration is a feature, not a bug.
397
+ We should only add new configuration rarely, and before doing so, ensure it
398
+ will be used. In fact, this is why we support using context fields for
399
+ experimental configuration. By letting users practice, we can find out if a
400
+ configuration was a good idea or not before committing to it, and potentially
401
+ sprawling our types.
402
+
403
+ In reflection, this approach worked well for the nearly 1.5 year period leading
404
+ to version 1.0. We've only had to create a single sub-configuration, `FSConfig`,
405
+ and it was well understood why when it occurred.
406
+
407
+ ## Why does `ModuleConfig.WithStartFunctions` default to `_start`?
408
+
409
+ We formerly had functions like `StartWASICommand` that would verify
410
+ preconditions and start WASI's `_start` command. However, this caused confusion
411
+ because both many languages compiled a WASI dependency, and many did so
412
+ inconsistently.
413
+
414
+ The conflict is that exported functions need to use features the language
415
+ runtime provides, such as garbage collection. There's a "chicken-egg problem"
416
+ where `_start` needs to complete in order for exported behavior to work.
417
+
418
+ For example, unlike `GOOS=wasip1` in Go 1.21, TinyGo's "wasi" target supports
419
+ function exports. So, the only way to use FFI style is via the "wasi" target.
420
+ Not explicitly calling `_start` before an ABI such as wapc-go, would crash, due
421
+ to setup not happening (e.g. to implement `panic`). Other embedders such as
422
+ Envoy also called `_start` for the same reason. To avoid a common problem for
423
+ users unaware of WASI, and also to simplify normal use of WASI (e.g. `main`),
424
+ we added `_start` to `ModuleConfig.WithStartFunctions`.
425
+
426
+ In cases of multiple initializers, such as in wapc-go, users can override this
427
+ to add the others *after* `_start`. Users who want to explicitly control
428
+ `_start`, such as some of our unit tests, can clear the start functions and
429
+ remove it.
430
+
431
+ This decision was made in 2022, and holds true in 2023, even with the
432
+ introduction of "wasix". It holds because "wasix" is backwards compatible with
433
+ "wasip1". In the future, there will be other ways to start applications, and
434
+ may not be backwards compatible with "wasip1".
435
+
436
+ Most notably WASI "Preview 2" is not implemented in a way compatible with
437
+ wasip1. Its start function is likely to be different, and defined in the
438
+ wasi-cli "world". When the design settles, and it is implemented by compilers,
439
+ wazero will attempt to support "wasip2". However, it won't do so in a way that
440
+ breaks existing compilers.
441
+
442
+ In other words, we won't remove `_start` if "wasip2" continues a path of an
443
+ alternate function name. If we did, we'd break existing users despite our
444
+ compatibility promise saying we don't. The most likely case is that when we
445
+ build-in something incompatible with "wasip1", that start function will be
446
+ added to the start functions list in addition to `_start`.
447
+
448
+ See http://wasix.org
449
+ See https://github.com/WebAssembly/wasi-cli
450
+
451
+ ## Runtime == Engine+Store
452
+ wazero defines a single user-type which combines the specification concept of `Store` with the unspecified `Engine`
453
+ which manages them.
454
+
455
+ ### Why not multi-store?
456
+ Multi-store isn't supported as the extra tier complicates lifecycle and locking. Moreover, in practice it is unusual for
457
+ there to be an engine that has multiple stores which have multiple modules. More often, it is the case that there is
458
+ either 1 engine with 1 store and multiple modules, or 1 engine with many stores, each having 1 non-host module. In worst
459
+ case, a user can use multiple runtimes until "multi-store" is better understood.
460
+
461
+ If later, we have demand for multiple stores, that can be accomplished by overload. e.g. `Runtime.InstantiateInStore` or
462
+ `Runtime.Store(name) Store`.
463
+
464
+ ## Exit
465
+
466
+ ### Why do we only return a `sys.ExitError` on a non-zero exit code?
467
+
468
+ It is reasonable to think an exit error should be returned, even if the code is
469
+ success (zero). Even on success, the module is no longer functional. For
470
+ example, function exports would error later. However, wazero does not. The only
471
+ time `sys.ExitError` is on error (non-zero).
472
+
473
+ This decision was to improve performance and ergonomics for guests that both
474
+ use WASI (have a `_start` function), and also allow custom exports.
475
+ Specifically, Rust, TinyGo and normal wasi-libc, don't exit the module during
476
+ `_start`. If they did, it would invalidate their function exports. This means
477
+ it is unlikely most compilers will change this behavior.
478
+
479
+ `GOOS=waspi1` from Go 1.21 does exit during `_start`. However, it doesn't
480
+ support other exports besides `_start`, and `_start` is not defined to be
481
+ called multiple times anyway.
482
+
483
+ Since `sys.ExitError` is not always returned, we added `Module.IsClosed` for
484
+ defensive checks. This helps integrators avoid calling functions which will
485
+ always fail.
486
+
487
+ ### Why panic with `sys.ExitError` after a host function exits?
488
+
489
+ Currently, the only portable way to stop processing code is via panic. For
490
+ example, WebAssembly "trap" instructions, such as divide by zero, are
491
+ implemented via panic. This ensures code isn't executed after it.
492
+
493
+ When code reaches the WASI `proc_exit` instruction, we need to stop processing.
494
+ Regardless of the exit code, any code invoked after exit would be in an
495
+ inconsistent state. This is likely why unreachable instructions are sometimes
496
+ inserted after exit: https://github.com/emscripten-core/emscripten/issues/12322
497
+
498
+ ## WASI
499
+
500
+ Unfortunately, [WASI Snapshot Preview 1](https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md) is not formally defined enough, and has APIs with ambiguous semantics.
501
+ This section describes how Wazero interprets and implements the semantics of several WASI APIs that may be interpreted differently by different wasm runtimes.
502
+ Those APIs may affect the portability of a WASI application.
503
+
504
+ ### Why don't we attempt to pass wasi-testsuite on user-defined `fs.FS`?
505
+
506
+ While most cases work fine on an `os.File` based implementation, we won't
507
+ promise wasi-testsuite compatibility on user defined wrappers of `os.DirFS`.
508
+ The only option for real systems is to use our `sysfs.FS`.
509
+
510
+ There are a lot of areas where windows behaves differently, despite the
511
+ `os.File` abstraction. This goes well beyond file locking concerns (e.g.
512
+ `EBUSY` errors on open files). For example, errors like `ACCESS_DENIED` aren't
513
+ properly mapped to `EPERM`. There are trickier parts too. `FileInfo.Sys()`
514
+ doesn't return enough information to build inodes needed for WASI. To rebuild
515
+ them requires the full path to the underlying file, not just its directory
516
+ name, and there's no way for us to get that information. At one point we tried,
517
+ but in practice things became tangled and functionality such as read-only
518
+ wrappers became untenable. Finally, there are version-specific behaviors which
519
+ are difficult to maintain even in our own code. For example, go 1.20 opens
520
+ files in a different way than versions before it.
521
+
522
+ ### Why aren't WASI rules enforced?
523
+
524
+ The [snapshot-01](https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md) version of WASI has a
525
+ number of rules for a "command module", but only the memory export rule is enforced. If a "_start" function exists, it
526
+ is enforced to be the correct signature and succeed, but the export itself isn't enforced. It follows that this means
527
+ exports are not required to be contained to a "_start" function invocation. Finally, the "__indirect_function_table"
528
+ export is also not enforced.
529
+
530
+ The reason for the exceptions are that implementations aren't following the rules. For example, TinyGo doesn't export
531
+ "__indirect_function_table", so crashing on this would make wazero unable to run TinyGo modules. Similarly, modules
532
+ loaded by wapc-go don't always define a "_start" function. Since "snapshot-01" is not a proper version, and certainly
533
+ not a W3C recommendation, there's no sense in breaking users over matters like this.
534
+
535
+ ### Why is I/O configuration not coupled to WASI?
536
+
537
+ WebAssembly System Interfaces (WASI) is a formalization of a practice that can be done anyway: Define a host function to
538
+ access a system interface, such as writing to STDOUT. WASI stalled at snapshot-01 and as of early 2023, is being
539
+ rewritten entirely.
540
+
541
+ This instability implies a need to transition between WASI specs, which places wazero in a position that requires
542
+ decoupling. For example, if code uses two different functions to call `fd_write`, the underlying configuration must be
543
+ centralized and decoupled. Otherwise, calls using the same file descriptor number will end up writing to different
544
+ places.
545
+
546
+ In short, wazero defined system configuration in `ModuleConfig`, not a WASI type. This allows end-users to switch from
547
+ one spec to another with minimal impact. This has other helpful benefits, as centralized resources are simpler to close
548
+ coherently (ex via `Module.Close`).
549
+
550
+ In reflection, this worked well as more ABI became usable in wazero.
551
+
552
+ ### Background on `ModuleConfig` design
553
+
554
+ WebAssembly 1.0 (20191205) specifies some aspects to control isolation between modules ([sandboxing](https://en.wikipedia.org/wiki/Sandbox_(computer_security))).
555
+ For example, `wasm.Memory` has size constraints and each instance of it is isolated from each other. While `wasm.Memory`
556
+ can be shared, by exporting it, it is not exported by default. In fact a WebAssembly Module (Wasm) has no memory by
557
+ default.
558
+
559
+ While memory is defined in WebAssembly 1.0 (20191205), many aspects are not. Let's use an example of `exec.Cmd` as for
560
+ example, a WebAssembly System Interfaces (WASI) command is implemented as a module with a `_start` function, and in many
561
+ ways acts similar to a process with a `main` function.
562
+
563
+ To capture "hello world" written to the console (stdout a.k.a. file descriptor 1) in `exec.Cmd`, you would set the
564
+ `Stdout` field accordingly, perhaps to a buffer. In WebAssembly 1.0 (20191205), the only way to perform something like
565
+ this is via a host function (ex `HostModuleFunctionBuilder`) and internally copy memory corresponding to that string
566
+ to a buffer.
567
+
568
+ WASI implements system interfaces with host functions. Concretely, to write to console, a WASI command `Module` imports
569
+ "fd_write" from "wasi_snapshot_preview1" and calls it with the `fd` parameter set to 1 (STDOUT).
570
+
571
+ The [snapshot-01](https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md) version of WASI has no
572
+ means to declare configuration, although its function definitions imply configuration for example if fd 1 should exist,
573
+ and if so where should it write. Moreover, snapshot-01 was last updated in late 2020 and the specification is being
574
+ completely rewritten as of early 2022. This means WASI as defined by "snapshot-01" will not clarify aspects like which
575
+ file descriptors are required. While it is possible a subsequent version may, it is too early to tell as no version of
576
+ WASI has reached a stage near W3C recommendation. Even if it did, module authors are not required to only use WASI to
577
+ write to console, as they can define their own host functions, such as they did before WASI existed.
578
+
579
+ wazero aims to serve Go developers as a primary function, and help them transition between WASI specifications. In
580
+ order to do this, we have to allow top-level configuration. To ensure isolation by default, `ModuleConfig` has WithXXX
581
+ that override defaults to no-op or empty. One `ModuleConfig` instance is used regardless of how many times the same WASI
582
+ functions are imported. The nil defaults allow safe concurrency in these situations, as well lower the cost when they
583
+ are never used. Finally, a one-to-one mapping with `Module` allows the module to close the `ModuleConfig` instead of
584
+ confusing users with another API to close.
585
+
586
+ Naming, defaults and validation rules of aspects like `STDIN` and `Environ` are intentionally similar to other Go
587
+ libraries such as `exec.Cmd` or `syscall.SetEnv`, and differences called out where helpful. For example, there's no goal
588
+ to emulate any operating system primitive specific to Windows (such as a 'c:\' drive). Moreover, certain defaults
589
+ working with real system calls are neither relevant nor safe to inherit: For example, `exec.Cmd` defaults to read STDIN
590
+ from a real file descriptor ("/dev/null"). Defaulting to this, vs reading `io.EOF`, would be unsafe as it can exhaust
591
+ file descriptors if resources aren't managed properly. In other words, blind copying of defaults isn't wise as it can
592
+ violate isolation or endanger the embedding process. In summary, we try to be similar to normal Go code, but often need
593
+ act differently and document `ModuleConfig` is more about emulating, not necessarily performing real system calls.
594
+
595
+ ## File systems
596
+
597
+ ### Motivation on `sys.FS`
598
+
599
+ The `sys.FS` abstraction in wazero was created because of limitations in
600
+ `fs.FS`, and `fs.File` in Go. Compilers targeting `wasip1` may access
601
+ functionality that writes new files. The ability to overcome this was requested
602
+ even before wazero was named this, via issue #21 in March 2021.
603
+
604
+ A month later, golang/go#45757 was raised by someone else on the same topic. As
605
+ of July 2023, this has not resolved to a writeable file system abstraction.
606
+
607
+ Over the next year more use cases accumulated, consolidated in March 2022 into
608
+ #390. This closed in January 2023 with a milestone of providing more
609
+ functionality, limited to users giving a real directory. This didn't yet expose
610
+ a file abstraction for general purpose use. Internally, this used `os.File`.
611
+ However, a wasm module instance is a virtual machine. Only supporting `os.File`
612
+ breaks sand-boxing use cases. Moreover, `os.File` is not an interface. Even
613
+ though this abstracts functionality, it does allow interception use cases.
614
+
615
+ Hence, a few days later in January 2023, we had more issues asking to expose an
616
+ abstraction, #1013 and later #1532, on use cases like masking access to files.
617
+ In other words, the use case requests never stopped, and aren't solved by
618
+ exposing only real files.
619
+
620
+ In summary, the primary motivation for exposing a replacement for `fs.FS` and
621
+ `fs.File` was around repetitive use case requests for years, around
622
+ interception and the ability to create new files, both virtual and real files.
623
+ While some use cases are solved with real files, not all are. Regardless, an
624
+ interface approach is necessary to ensure users can intercept I/O operations.
625
+
626
+ ### Why doesn't `sys.File` have a `Fd()` method?
627
+
628
+ There are many features we could expose. We could make File expose underlying
629
+ file descriptors in case they are supported, for integration of system calls
630
+ that accept multiple ones, namely `poll` for multiplexing. This special case is
631
+ described in a subsequent section.
632
+
633
+ As noted above, users have been asking for a file abstraction for over two
634
+ years, and a common answer was to wait. Making users wait is a problem,
635
+ especially so long. Good reasons to make people wait are stabilization. Edge
636
+ case features are not a great reason to hold abstractions from users.
637
+
638
+ Another reason is implementation difficulty. Go did not attempt to abstract
639
+ file descriptors. For example, unlike `fs.ReadFile` there is no `fs.FdFile`
640
+ interface. Most likely, this is because file descriptors are an implementation
641
+ detail of common features. Programming languages, including Go, do not require
642
+ end users to know about file descriptors. Types such as `fs.File` can be used
643
+ without any knowledge of them. Implementations may or may not have file
644
+ descriptors. For example, in Go, `os.DirFS` has underlying file descriptors
645
+ while `embed.FS` does not.
646
+
647
+ Despite this, some may want to expose a non-standard interface because
648
+ `os.File` has `Fd() uintptr` to return a file descriptor. Mainly, this is
649
+ handy to integrate with `syscall` package functions (on `GOOS` values that
650
+ declare them). Notice, though that `uintptr` is unsafe and not an abstraction.
651
+ Close inspection will find some `os.File` types internally use `poll.FD`
652
+ instead, yet this is not possible to use abstractly because that type is not
653
+ exposed. For example, `plan9` uses a different type than `poll.FD`. In other
654
+ words, even in real files, `Fd()` is not wholly portable, despite it being
655
+ useful on many operating systems with the `syscall` package.
656
+
657
+ The reasons above, why Go doesn't abstract `FdFile` interface are a subset of
658
+ reasons why `sys.File` does not. If we exposed `File.Fd()` we not only would
659
+ have to declare all the edge cases that Go describes including impact of
660
+ finalizers, we would have to describe these in terms of virtualized files.
661
+ Then, we would have to reason with this value vs our existing virtualized
662
+ `sys.FileTable`, mapping whatever type we return to keys in that table, also
663
+ in consideration of garbage collection impact. The combination of issues like
664
+ this could lead down a path of not implementing a file system abstraction at
665
+ all, and instead a weak key mapped abstraction of the `syscall` package. Once
666
+ we finished with all the edge cases, we would have lost context of the original
667
+ reason why we started.. simply to allow file write access!
668
+
669
+ When wazero attempts to do more than what the Go programming language team, it
670
+ has to be carefully evaluated, to:
671
+ * Be possible to implement at least for `os.File` backed files
672
+ * Not be confusing or cognitively hard for virtual file systems and normal use.
673
+ * Affordable: custom code is solely the responsible by the core team, a much
674
+ smaller group of individuals than who maintain the Go programming language.
675
+
676
+ Due to problems well known in Go, consideration of the end users who constantly
677
+ ask for basic file system functionality, and the difficulty virtualizing file
678
+ descriptors at multiple levels, we don't expose `Fd()` and likely won't ever
679
+ expose `Fd()` on `sys.File`.
680
+
681
+ ### Why does `sys.File` have a `Poll()` method, while `sys.FS` does not?
682
+
683
+ wazero exposes `File.Poll` which allows one-at-a-time poll use cases,
684
+ requested by multiple users. This not only includes abstract tests such as
685
+ Go 1.21 `GOOS=wasip1`, but real use cases including python and container2wasm
686
+ repls, as well listen sockets. The main use cases is non-blocking poll on a
687
+ single file. Being a single file, this has no risk of problems such as
688
+ head-of-line blocking, even when emulated.
689
+
690
+ The main use case of multi-poll are bidirectional network services, something
691
+ not used in `GOOS=wasip1` standard libraries, but could be in the future.
692
+ Moving forward without a multi-poller allows wazero to expose its file system
693
+ abstraction instead of continuing to hold back it back for edge cases. We'll
694
+ continue discussion below regardless, as rationale was requested.
695
+
696
+ You can loop through multiple `sys.File`, using `File.Poll` to see if an event
697
+ is ready, but there is a head-of-line blocking problem. If a long timeout is
698
+ used, bad luck could have a file that has nothing to read or write before one
699
+ that does. This could cause more blocking than necessary, even if you could
700
+ poll the others just after with a zero timeout. What's worse than this is if
701
+ unlimited blocking was used (`timeout=-1`). The host implementations could use
702
+ goroutines to avoid this, but interrupting a "forever" poll is problematic. All
703
+ of these are reasons to consider a multi-poll API, but do not require exporting
704
+ `File.Fd()`.
705
+
706
+ Should multi-poll becomes critical, `sys.FS` could expose a `Poll` function
707
+ like below, despite it being the non-portable, complicated if possible to
708
+ implement on all platforms and virtual file systems.
709
+ ```go
710
+ ready, errno := fs.Poll([]sys.PollFile{{f1, sys.POLLIN}, {f2, sys.POLLOUT}}, timeoutMillis)
711
+ ```
712
+
713
+ A real filesystem could handle this by using an approach like the internal
714
+ `unix.Poll` function in Go, passing file descriptors on unix platforms, or
715
+ returning `sys.ENOSYS` for unsupported operating systems. Implementation for
716
+ virtual files could have a strategy around timeout to avoid the worst case of
717
+ head-of-line blocking (unlimited timeout).
718
+
719
+ Let's remember that when designing abstractions, it is not best to add an
720
+ interface for everything. Certainly, Go doesn't, as evidenced by them not
721
+ exposing `poll.FD` in `os.File`! Such a multi-poll could be limited to
722
+ built-in filesystems in the wazero repository, avoiding complexity of trying to
723
+ support and test this abstractly. This would still permit multiplexing for CLI
724
+ users, and also permit single file polling as exists now.
725
+
726
+ ### Why doesn't wazero implement the working directory?
727
+
728
+ An early design of wazero's API included a `WithWorkDirFS` which allowed
729
+ control over which file a relative path such as "./config.yml" resolved to,
730
+ independent of the root file system. This intended to help separate concerns
731
+ like mutability of files, but it didn't work and was removed.
732
+
733
+ Compilers that target wasm act differently with regard to the working
734
+ directory. For example, wasi-libc, used by TinyGo,
735
+ tracks working directory changes in compiled wasm instead: initially "/" until
736
+ code calls `chdir`. Zig assumes the first pre-opened file descriptor is the
737
+ working directory.
738
+
739
+ The only place wazero can standardize a layered concern is via a host function.
740
+ Since WASI doesn't use host functions to track the working directory, we can't
741
+ standardize the storage and initial value of it.
742
+
743
+ Meanwhile, code may be able to affect the working directory by compiling
744
+ `chdir` into their main function, using an argument or ENV for the initial
745
+ value (possibly `PWD`). Those unable to control the compiled code should only
746
+ use absolute paths in configuration.
747
+
748
+ See
749
+ * https://github.com/golang/go/blob/go1.24.0/src/syscall/fs_js.go#L341
750
+ * https://github.com/WebAssembly/wasi-libc/pull/214#issue-673090117
751
+ * https://github.com/ziglang/zig/blob/53a9ee699a35a3d245ab6d1dac1f0687a4dcb42c/src/main.zig#L32
752
+
753
+ ### Why ignore the error returned by io.Reader when n > 1?
754
+
755
+ Per https://pkg.go.dev/io#Reader, if we receive an error, any bytes read should
756
+ be processed first. At the syscall abstraction (`fd_read`), the caller is the
757
+ processor, so we can't process the bytes inline and also return the error (as
758
+ `EIO`).
759
+
760
+ Let's assume we want to return the bytes read on error to the caller. This
761
+ implies we at least temporarily ignore the error alongside them. The choice
762
+ remaining is whether to persist the error returned with the read until a
763
+ possible next call, or ignore the error.
764
+
765
+ If we persist an error returned, it would be coupled to a file descriptor, but
766
+ effectively it is boolean as this case coerces to `EIO`. If we track a "last
767
+ error" on a file descriptor, it could be complicated for a couple reasons
768
+ including whether the error is transient or permanent, or if the error would
769
+ apply to any FD operation, or just read. Finally, there may never be a
770
+ subsequent read as perhaps the bytes leading up to the error are enough to
771
+ satisfy the processor.
772
+
773
+ This decision boils down to whether or not to track an error bit per file
774
+ descriptor or not. If not, the assumption is that a subsequent operation would
775
+ also error, this time without reading any bytes.
776
+
777
+ The current opinion is to go with the simplest path, which is to return the
778
+ bytes read and ignore the error the there were any. Assume a subsequent
779
+ operation will err if it needs to. This helps reduce the complexity of the code
780
+ in wazero and also accommodates the scenario where the bytes read are enough to
781
+ satisfy its processor.
782
+
783
+ ### File descriptor allocation strategy
784
+
785
+ File descriptor allocation currently uses a strategy similar the one implemented
786
+ by unix systems: when opening a file, the lowest unused number is picked.
787
+
788
+ The WASI standard documents that programs cannot expect that file descriptor
789
+ numbers will be allocated with a lowest-first strategy, and they should instead
790
+ assume the values will be random. Since _random_ is a very imprecise concept in
791
+ computers, we technically satisfying the implementation with the descriptor
792
+ allocation strategy we use in Wazero. We could imagine adding more _randomness_
793
+ to the descriptor selection process, however this should never be used as a
794
+ security measure to prevent applications from guessing the next file number so
795
+ there are no strong incentives to complicate the logic.
796
+
797
+ ### Why does `FSConfig.WithDirMount` not match behaviour with `os.DirFS`?
798
+
799
+ It may seem that we should require any feature that seems like a standard
800
+ library in Go, to behave the same way as the standard library. Doing so would
801
+ present least surprise to Go developers. In the case of how we handle
802
+ filesystems, we break from that as it is incompatible with the expectations of
803
+ WASI, the most commonly implemented filesystem ABI.
804
+
805
+ The main reason is that `os.DirFS` is a virtual filesystem abstraction while
806
+ WASI is an abstraction over syscalls. For example, the signature of `fs.Open`
807
+ does not permit use of flags. This creates conflict on what default behaviors
808
+ to take when Go implemented `os.DirFS`. On the other hand, `path_open` can pass
809
+ flags, and in fact tests require them to be honored in specific ways.
810
+
811
+ This conflict requires us to choose what to be more compatible with, and which
812
+ type of user to surprise the least. We assume there will be more developers
813
+ compiling code to wasm than developers of custom filesystem plugins, and those
814
+ compiling code to wasm will be better served if we are compatible with WASI.
815
+ Hence on conflict, we prefer WASI behavior vs the behavior of `os.DirFS`.
816
+
817
+ See https://github.com/WebAssembly/wasi-testsuite
818
+ See https://github.com/golang/go/issues/58141
819
+
820
+ ## Why is our `Readdir` function more like Go's `os.File` than POSIX `readdir`?
821
+
822
+ At one point we attempted to move from a bulk `Readdir` function to something
823
+ more like the POSIX `DIR` struct, exposing functions like `telldir`, `seekdir`
824
+ and `readdir`. However, we chose the design more like `os.File.Readdir`,
825
+ because it performs and fits wasip1 better.
826
+
827
+ ### wasip1/wasix
828
+
829
+ `fd_readdir` in wasip1 (and so also wasix) is like `getdents` in Linux, not
830
+ `readdir` in POSIX. `getdents` is more like Go's `os.File.Readdir`.
831
+
832
+ We currently have an internal type `sys.DirentCache` which only is used by
833
+ wasip1 or wasix. When `HostModuleBuilder` adds support for instantiation state,
834
+ we could move this to the `wasi_snapshot_preview1` package. Meanwhile, all
835
+ filesystem code is internal anyway, so this special-case is acceptable.
836
+
837
+ ### wasip2
838
+
839
+ `directory-entry-stream` in wasi-filesystem preview2 is defined in component
840
+ model, not an ABI, but in wasmtime it is a consuming iterator. A consuming
841
+ iterator is easy to support with anything (like `Readdir(1)`), even if it is
842
+ inefficient as you can neither bulk read nor skip. The implementation of the
843
+ preview1 adapter (uses preview2) confirms this. They use a dirent cache similar
844
+ in some ways to our `sysfs.DirentCache`. As there is no seek concept in
845
+ preview2, they interpret the cookie as numeric and read on repeat entries when
846
+ a cache wasn't available. Note: we currently do not skip-read like this as it
847
+ risks buffering large directories, and no user has requested entries before the
848
+ cache, yet.
849
+
850
+ Regardless, wasip2 is not complete until the end of 2023. We can defer design
851
+ discussion until after it is stable and after the reference impl wasmtime
852
+ implements it.
853
+
854
+ See
855
+ * https://github.com/WebAssembly/wasi-filesystem/blob/ef9fc87c07323a6827632edeb6a7388b31266c8e/example-world.md#directory_entry_stream
856
+ * https://github.com/bytecodealliance/wasmtime/blob/b741f7c79d72492d17ab8a29c8ffe4687715938e/crates/wasi/src/preview2/preview2/filesystem.rs#L286-L296
857
+ * https://github.com/bytecodealliance/preview2-prototyping/blob/e4c04bcfbd11c42c27c28984948d501a3e168121/crates/wasi-preview1-component-adapter/src/lib.rs#L2131-L2137
858
+ * https://github.com/bytecodealliance/preview2-prototyping/blob/e4c04bcfbd11c42c27c28984948d501a3e168121/crates/wasi-preview1-component-adapter/src/lib.rs#L936
859
+
860
+ ### wasip3
861
+
862
+ `directory-entry-stream` is documented to change significantly in wasip3 moving
863
+ from synchronous to synchronous streams. This is dramatically different than
864
+ POSIX `readdir` which is synchronous.
865
+
866
+ Regardless, wasip3 is not complete until after wasip2, which means 2024 or
867
+ later. We can defer design discussion until after it is stable and after the
868
+ reference impl wasmtime implements it.
869
+
870
+ See
871
+ * https://github.com/WebAssembly/WASI/blob/ddfe3d1dda5d1473f37ecebc552ae20ce5fd319a/docs/WitInWasi.md#Streams
872
+ * https://docs.google.com/presentation/d/1MNVOZ8hdofO3tI0szg_i-Yoy0N2QPU2C--LzVuoGSlE/edit#slide=id.g1270ef7d5b6_0_662
873
+
874
+ ### How do we implement `Pread` with an `fs.File`?
875
+
876
+ `ReadAt` is the Go equivalent to `pread`: it does not affect, and is not
877
+ affected by, the underlying file offset. Unfortunately, `io.ReaderAt` is not
878
+ implemented by all `fs.File`. For example, as of Go 1.19, `embed.openFile` does
879
+ not.
880
+
881
+ The initial implementation of `fd_pread` instead used `Seek`. To avoid a
882
+ regression, we fall back to `io.Seeker` when `io.ReaderAt` is not supported.
883
+
884
+ This requires obtaining the initial file offset, seeking to the intended read
885
+ offset, and resetting the file offset the initial state. If this final seek
886
+ fails, the file offset is left in an undefined state. This is not thread-safe.
887
+
888
+ While seeking per read seems expensive, the common case of `embed.openFile` is
889
+ only accessing a single int64 field, which is cheap.
890
+
891
+ ### Pre-opened files
892
+
893
+ WASI includes `fd_prestat_get` and `fd_prestat_dir_name` functions used to
894
+ learn any directory paths for file descriptors open at initialization time.
895
+
896
+ For example, `__wasilibc_register_preopened_fd` scans any file descriptors past
897
+ STDERR (1) and invokes `fd_prestat_dir_name` to learn any path prefixes they
898
+ correspond to. Zig's `preopensAlloc` does similar. These pre-open functions are
899
+ not used again after initialization.
900
+
901
+ wazero supports stdio pre-opens followed by any mounts e.g `.:/`. The guest
902
+ path is a directory and its name, e.g. "/" is returned by `fd_prestat_dir_name`
903
+ for file descriptor 3 (STDERR+1). The first longest match wins on multiple
904
+ pre-opens, which allows a path like "/tmp" to match regardless of order vs "/".
905
+
906
+ See
907
+ * https://github.com/WebAssembly/wasi-libc/blob/a02298043ff551ce1157bc2ee7ab74c3bffe7144/libc-bottom-half/sources/preopens.c
908
+ * https://github.com/ziglang/zig/blob/9cb06f3b8bf9ea6b5e5307711bc97328762d6a1d/lib/std/fs/wasi.zig#L50-L53
909
+
910
+ ### fd_prestat_dir_name
911
+
912
+ `fd_prestat_dir_name` is a WASI function to return the path of the pre-opened
913
+ directory of a file descriptor. It has the following three parameters, and the
914
+ third `path_len` has ambiguous semantics.
915
+
916
+ * `fd`: a file descriptor
917
+ * `path`: the offset for the result path
918
+ * `path_len`: In wazero, `FdPrestatDirName` writes the result path string to
919
+ `path` offset for the exact length of `path_len`.
920
+
921
+ Wasmer considers `path_len` to be the maximum length instead of the exact
922
+ length that should be written.
923
+ See https://github.com/wasmerio/wasmer/blob/3463c51268ed551933392a4063bd4f8e7498b0f6/lib/wasi/src/syscalls/mod.rs#L764
924
+
925
+ The semantics in wazero follows that of wasmtime.
926
+ See https://github.com/bytecodealliance/wasmtime/blob/2ca01ae9478f199337cf743a6ab543e8c3f3b238/crates/wasi-common/src/snapshots/preview_1.rs#L578-L582
927
+
928
+ Their semantics match when `path_len` == the length of `path`, so in practice
929
+ this difference won't matter match.
930
+
931
+ ## fd_readdir
932
+
933
+ ### Why does "wasi_snapshot_preview1" require dot entries when POSIX does not?
934
+
935
+ In October 2019, WASI project knew requiring dot entries ("." and "..") was not
936
+ documented in preview1, not required by POSIX and problematic to synthesize.
937
+ For example, Windows runtimes backed by `FindNextFileW` could not return these.
938
+ A year later, the tag representing WASI preview 1 (`snapshot-01`) was made.
939
+ This did not include the requested change of making dot entries optional.
940
+
941
+ The `phases/snapshot/docs.md` document was altered in subsequent years in
942
+ significant ways, often in lock-step with wasmtime or wasi-libc. In January
943
+ 2022, `sock_accept` was added to `phases/snapshot/docs.md`, a document later
944
+ renamed to later renamed to `legacy/preview1/docs.md`.
945
+
946
+ As a result, the ABI and behavior remained unstable: The `snapshot-01` tag was
947
+ not an effective basis of portability. A test suite was requested well before
948
+ this tag, in April 2019. Meanwhile, compliance had no meaning. Developers had
949
+ to track changes to the latest doc, while clarifying with wasi-libc or wasmtime
950
+ behavior. This lack of stability could have permitted a fix to the dot entries
951
+ problem, just as it permitted changes desired by other users.
952
+
953
+ In November 2022, the wasi-testsuite project began and started solidifying
954
+ expectations. This quickly led to changes in runtimes and the spec doc. WASI
955
+ began importing tests from wasmtime as required behaviors for all runtimes.
956
+ Some changes implied changes to wasi-libc. For example, `readdir` began to
957
+ imply inode fan-outs, which caused performance regressions. Most notably a
958
+ test merged in January required dot entries. Tests were merged without running
959
+ against any runtime, and even when run ad-hoc only against Linux. Hence,
960
+ portability issues mentioned over three years earlier did not trigger any
961
+ failure until wazero (which tests Windows) noticed.
962
+
963
+ In the same month, wazero requested to revert this change primarily because
964
+ Go does not return them from `os.ReadDir`, and materializing them is
965
+ complicated due to tests also requiring inodes. Moreover, they are discarded by
966
+ not just Go, but other common programming languages. This was rejected by the
967
+ WASI lead for preview1, but considered for the completely different ABI named
968
+ preview2.
969
+
970
+ In February 2023, the WASI chair declared that new rule requiring preview1 to
971
+ return dot entries "was decided by the subgroup as a whole", citing meeting
972
+ notes. According to these notes, the WASI lead stated incorrectly that POSIX
973
+ conformance required returning dot entries, something it explicitly says are
974
+ optional. In other words, he said filtering them out would make Preview1
975
+ non-conforming, and asked if anyone objects to this. The co-chair was noted to
976
+ say "Because there are existing P1 programs, we shouldn’t make changes like
977
+ this." No other were recorded to say anything.
978
+
979
+ In summary, preview1 was changed retrospectively to require dot entries and
980
+ preview2 was changed to require their absence. This rule was reverse engineered
981
+ from wasmtime tests, and affirmed on two false premises:
982
+
983
+ * POSIX compliance requires dot entries
984
+ * POSIX literally says these are optional
985
+ * WASI cannot make changes because there are existing P1 programs.
986
+ * Changes to Preview 1 happened before and after this topic.
987
+
988
+ As of June 2023, wasi-testsuite still only runs on Linux, so compliance of this
989
+ rule on Windows is left to runtimes to decide to validate. The preview2 adapter
990
+ uses fake cookies zero and one to refer to dot dirents, uses a real inode for
991
+ the dot(".") entry and zero inode for dot-dot("..").
992
+
993
+ See https://github.com/WebAssembly/wasi-filesystem/issues/3
994
+ See https://github.com/WebAssembly/WASI/tree/snapshot-01
995
+ See https://github.com/WebAssembly/WASI/issues/9
996
+ See https://github.com/WebAssembly/WASI/pull/458
997
+ See https://github.com/WebAssembly/wasi-testsuite/pull/32
998
+ See https://github.com/WebAssembly/wasi-libc/pull/345
999
+ See https://github.com/WebAssembly/wasi-testsuite/issues/52
1000
+ See https://github.com/WebAssembly/WASI/pull/516
1001
+ See https://github.com/WebAssembly/meetings/blob/main/wasi/2023/WASI-02-09.md#should-preview1-fd_readdir-filter-out--and-
1002
+ See https://github.com/bytecodealliance/preview2-prototyping/blob/e4c04bcfbd11c42c27c28984948d501a3e168121/crates/wasi-preview1-component-adapter/src/lib.rs#L1026-L1041
1003
+
1004
+ ### Why are dot (".") and dot-dot ("..") entries problematic?
1005
+
1006
+ When reading a directory, dot (".") and dot-dot ("..") entries are problematic.
1007
+ For example, Go does not return them from `os.ReadDir`, and materializing them
1008
+ is complicated (at least dot-dot is).
1009
+
1010
+ A directory entry has stat information in it. The stat information includes
1011
+ inode which is used for comparing file equivalence. In the simple case of dot,
1012
+ we could materialize a special entry to expose the same info as stat on the fd
1013
+ would return. However, doing this and not doing dot-dot would cause confusion,
1014
+ and dot-dot is far more tricky. To back-fill inode information about a parent
1015
+ directory would be costly and subtle. For example, the pre-open (mount) of the
1016
+ directory may be different than its logical parent. This is easy to understand
1017
+ when considering the common case of mounting "/" and "/tmp" as pre-opens. To
1018
+ implement ".." from "/tmp" requires information from a separate pre-open, this
1019
+ includes state to even know the difference. There are easier edge cases as
1020
+ well, such as the decision to not return ".." from a root path. In any case,
1021
+ this should start to explain that faking entries when underlying stdlib doesn't
1022
+ return them is tricky and requires quite a lot of state.
1023
+
1024
+ Another issue is around the `Dirent.Off` value of a directory entry, sometimes
1025
+ called a "cookie" in Linux man pagers. When the host operating system or
1026
+ library function does not return dot entries, to support functions such as
1027
+ `seekdir`, you still need a value for `Dirent.Off`. Naively, you can synthesize
1028
+ these by choosing sequential offsets zero and one. However, POSIX strictly says
1029
+ offsets should be treated opaquely. The backing filesystem could use these to
1030
+ represent real entries. For example, a directory with one entry could use zero
1031
+ as the `Dirent.Off` value. If you also used zero for the "." dirent, there
1032
+ would be a clash. This means if you synthesize `Dirent.Off` for any entry, you
1033
+ need to synthesize this value for all entries. In practice, the simplest way is
1034
+ using an incrementing number, such as done in the WASI preview2 adapter.
1035
+
1036
+ Working around these issues causes expense to all users of wazero, so we'd
1037
+ then look to see if that would be justified or not. However, the most common
1038
+ compilers involved in end user questions, as of early 2023 are TinyGo, Rust and
1039
+ Zig. All of these compile code which ignores dot and dot-dot entries. In other
1040
+ words, faking these entries would not only cost our codebase with complexity,
1041
+ but it would also add unnecessary overhead as the values aren't commonly used.
1042
+
1043
+ The final reason why we might do this, is an end users or a specification
1044
+ requiring us to. As of early 2023, no end user has raised concern over Go and
1045
+ by extension wazero not returning dot and dot-dot. The snapshot-01 spec of WASI
1046
+ does not mention anything on this point. Also, POSIX has the following to say,
1047
+ which summarizes to "these are optional"
1048
+
1049
+ > The readdir() function shall not return directory entries containing empty names. If entries for dot or dot-dot exist, one entry shall be returned for dot and one entry shall be returned for dot-dot; otherwise, they shall not be returned.
1050
+
1051
+ Unfortunately, as described above, the WASI project decided in early 2023 to
1052
+ require dot entries in both the spec and the wasi-testsuite. For only this
1053
+ reason, wazero adds overhead to synthesize dot entries despite it being
1054
+ unnecessary for most users.
1055
+
1056
+ See https://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html
1057
+ See https://github.com/golang/go/blob/go1.24.0/src/os/dir_unix.go#L122-L124
1058
+ See https://github.com/bytecodealliance/preview2-prototyping/blob/e4c04bcfbd11c42c27c28984948d501a3e168121/crates/wasi-preview1-component-adapter/src/lib.rs#L1026-L1041
1059
+
1060
+ ### Why don't we pre-populate an inode for the dot-dot ("..") entry?
1061
+
1062
+ We only populate an inode for dot (".") because wasi-testsuite requires it, and
1063
+ we likely already have it (because we cache it). We could attempt to populate
1064
+ one for dot-dot (".."), but chose not to.
1065
+
1066
+ Firstly, wasi-testsuite does not require the inode of dot-dot, possibly because
1067
+ the wasip2 adapter doesn't populate it (but we don't really know why).
1068
+
1069
+ The only other reason to populate it would be to avoid wasi-libc's stat fanout
1070
+ when it is missing. However, wasi-libc explicitly doesn't fan-out to lstat on
1071
+ the ".." entry on a zero ino.
1072
+
1073
+ Fetching dot-dot's inode despite the above not only doesn't help wasi-libc, but
1074
+ it also hurts languages that don't use it, such as Go. These languages would
1075
+ pay a stat syscall penalty even if they don't need the inode. In fact, Go
1076
+ discards both dot entries!
1077
+
1078
+ In summary, there are no significant upsides in attempting to pre-fetch
1079
+ dot-dot's inode, and there are downsides to doing it anyway.
1080
+
1081
+ See
1082
+ * https://github.com/WebAssembly/wasi-libc/blob/bd950eb128bff337153de217b11270f948d04bb4/libc-bottom-half/cloudlibc/src/libc/dirent/readdir.c#L87-L94
1083
+ * https://github.com/WebAssembly/wasi-testsuite/blob/main/tests/rust/src/bin/fd_readdir.rs#L108
1084
+ * https://github.com/bytecodealliance/preview2-prototyping/blob/e4c04bcfbd11c42c27c28984948d501a3e168121/crates/wasi-preview1-component-adapter/src/lib.rs#L1037
1085
+
1086
+ ### Why don't we require inodes to be non-zero?
1087
+
1088
+ We don't require a non-zero value for `Dirent.Ino` because doing so can prevent
1089
+ a real one from resolving later via `Stat_t.Ino`.
1090
+
1091
+ We define `Ino` like `d_ino` in POSIX which doesn't special-case zero. It can
1092
+ be zero for a few reasons:
1093
+
1094
+ * The file is not a regular file or directory.
1095
+ * The underlying filesystem does not support inodes. e.g. embed:fs
1096
+ * A directory doesn't include inodes, but a later stat can. e.g. Windows
1097
+ * The backend is based on wasi-filesystem (a.k.a wasip2), which has
1098
+ `directory_entry.inode` optional, and might remove it entirely.
1099
+
1100
+ There are other downsides to returning a zero inode in widely used compilers:
1101
+
1102
+ * File equivalence utilities, like `os.SameFile` will not work.
1103
+ * wasi-libc's `wasip1` mode will call `lstat` and attempt to retrieve a
1104
+ non-zero value (unless the entry is named "..").
1105
+
1106
+ A new compiler may accidentally skip a `Dirent` with a zero `Ino` if emulating
1107
+ a non-POSIX function and re-using `Dirent.Ino` for `d_fileno`.
1108
+
1109
+ * Linux `getdents` doesn't define `d_fileno` must be non-zero
1110
+ * BSD `getdirentries` is implementation specific. For example, OpenBSD will
1111
+ return dirents with a zero `d_fileno`, but Darwin will skip them.
1112
+
1113
+ The above shouldn't be a problem, even in the case of BSD, because `wasip1` is
1114
+ defined more in terms of `getdents` than `getdirentries`. The bottom half of
1115
+ either should treat `wasip1` (or any similar ABI such as wasix or wasip2) as a
1116
+ different operating system and either use different logic that doesn't skip, or
1117
+ synthesize a fake non-zero `d_fileno` when `d_ino` is zero.
1118
+
1119
+ However, this has been a problem. Go's `syscall.ParseDirent` utility is shared
1120
+ for all `GOOS=unix`. For simplicity, this abstracts `direntIno` with data from
1121
+ `d_fileno` or `d_ino`, and drops if either are zero, even if `d_fileno` is the
1122
+ only field with zero explicitly defined. This led to a change to special case
1123
+ `GOOS=wasip1` as otherwise virtual files would be unconditionally skipped.
1124
+
1125
+ In practice, this problem is rather unique due to so many compilers relying on
1126
+ wasi-libc, which tolerates a zero inode. For example, while issues were
1127
+ reported about the performance regression when wasi-libc began doing a fan-out
1128
+ on zero `Dirent.Ino`, no issues were reported about dirents being dropped as a
1129
+ result.
1130
+
1131
+ In summary, rather than complicating implementation and forcing non-zero inodes
1132
+ for a rare case, we permit zero. We instead document this topic thoroughly, so
1133
+ that emerging compilers can re-use the research and reference it on conflict.
1134
+ We also document that `Ino` should be non-zero, so that users implementing that
1135
+ field will attempt to get it.
1136
+
1137
+ See
1138
+ * https://github.com/WebAssembly/wasi-filesystem/pull/81
1139
+ * https://github.com/WebAssembly/wasi-libc/blob/bd950eb128bff337153de217b11270f948d04bb4/libc-bottom-half/cloudlibc/src/libc/dirent/readdir.c#L87-L94
1140
+ * https://linux.die.net/man/3/getdents
1141
+ * https://www.unix.com/man-page/osx/2/getdirentries/
1142
+ * https://man.openbsd.org/OpenBSD-5.4/getdirentries.2
1143
+ * https://github.com/golang/go/blob/go1.24.0/src/syscall/dirent.go#L57-L101
1144
+ * https://go-review.googlesource.com/c/go/+/507915
1145
+
1146
+ ## sys.Walltime and Nanotime
1147
+
1148
+ The `sys` package has two function types, `Walltime` and `Nanotime` for real
1149
+ and monotonic clock exports. The naming matches conventions used in Go.
1150
+
1151
+ ```go
1152
+ func time_now() (sec int64, nsec int32, mono int64) {
1153
+ sec, nsec = walltime()
1154
+ return sec, nsec, nanotime()
1155
+ }
1156
+ ```
1157
+
1158
+ Splitting functions for wall and clock time allow implementations to choose
1159
+ whether to implement the clock once (as in Go), or split them out.
1160
+
1161
+ Each can be configured with a `ClockResolution`, although is it usually
1162
+ incorrect as detailed in a sub-heading below. The only reason for exposing this
1163
+ is to satisfy WASI:
1164
+
1165
+ See https://github.com/WebAssembly/wasi-clocks
1166
+
1167
+ ### Why default to fake time?
1168
+
1169
+ WebAssembly has an implicit design pattern of capabilities based security. By
1170
+ defaulting to a fake time, we reduce the chance of timing attacks, at the cost
1171
+ of requiring configuration to opt-into real clocks.
1172
+
1173
+ See https://gruss.cc/files/fantastictimers.pdf for an example attacks.
1174
+
1175
+ ### Why does fake time increase on reading?
1176
+
1177
+ Both the fake nanotime and walltime increase by 1ms on reading. Particularly in
1178
+ the case of nanotime, this prevents spinning.
1179
+
1180
+ ### Why not `time.Clock`?
1181
+
1182
+ wazero can't use `time.Clock` as a plugin for clock implementation as it is
1183
+ only substitutable with build flags (`faketime`) and conflates wall and
1184
+ monotonic time in the same call.
1185
+
1186
+ Go's `time.Clock` was added monotonic time after the fact. For portability with
1187
+ prior APIs, a decision was made to combine readings into the same API call.
1188
+
1189
+ See https://go.googlesource.com/proposal/+/master/design/12914-monotonic.md
1190
+
1191
+ WebAssembly time imports do not have the same concern. In fact even Go's
1192
+ imports for clocks split walltime from nanotime readings.
1193
+
1194
+ See https://github.com/golang/go/blob/go1.24.0/lib/wasm/wasm_exec.js#L258-L268
1195
+
1196
+ Finally, Go's clock is not an interface. WebAssembly users who want determinism
1197
+ or security need to be able to substitute an alternative clock implementation
1198
+ from the host process one.
1199
+
1200
+ ### `ClockResolution`
1201
+
1202
+ A clock's resolution is hardware and OS dependent so requires a system call to retrieve an accurate value.
1203
+ Go does not provide a function for getting resolution, so without CGO we don't have an easy way to get an actual
1204
+ value. For now, we return fixed values of 1us for realtime and 1ns for monotonic, assuming that realtime clocks are
1205
+ often lower precision than monotonic clocks. In the future, this could be improved by having OS+arch specific assembly
1206
+ to make syscalls.
1207
+
1208
+ For example, Go implements time.Now for linux-amd64 with this [assembly](https://github.com/golang/go/blob/go1.24.0/src/runtime/time_linux_amd64.s).
1209
+ Because retrieving resolution is not generally called often, unlike getting time, it could be appropriate to only
1210
+ implement the fallback logic that does not use VDSO (executing syscalls in user mode). The syscall for clock_getres
1211
+ is 229 and should be usable. https://pkg.go.dev/syscall#pkg-constants.
1212
+
1213
+ If implementing similar for Windows, [mingw](https://github.com/mirror/mingw-w64/blob/v12.0.0/mingw-w64-libraries/winpthreads/src/clock.c#L54)
1214
+ is often a good source to find the Windows API calls that correspond
1215
+ to a POSIX method.
1216
+
1217
+ Writing assembly would allow making syscalls without CGO, but comes with the cost that it will require implementations
1218
+ across many combinations of OS and architecture.
1219
+
1220
+ ## sys.Nanosleep
1221
+
1222
+ All major programming languages have a `sleep` mechanism to block for a
1223
+ duration. Sleep is typically implemented by a WASI `poll_oneoff` relative clock
1224
+ subscription.
1225
+
1226
+ For example, the below ends up calling `wasi_snapshot_preview1.poll_oneoff`:
1227
+
1228
+ ```zig
1229
+ const std = @import("std");
1230
+ pub fn main() !void {
1231
+ std.time.sleep(std.time.ns_per_s * 5);
1232
+ }
1233
+ ```
1234
+
1235
+ Besides Zig, this is also the case with TinyGo (`-target=wasi`) and Rust
1236
+ (`--target wasm32-wasi`).
1237
+
1238
+ We decided to expose `sys.Nanosleep` to allow overriding the implementation
1239
+ used in the common case, even if it isn't used by Go, because this gives an
1240
+ easy and efficient closure over a common program function. We also documented
1241
+ `sys.Nanotime` to warn users that some compilers don't optimize sleep.
1242
+
1243
+ ## sys.Osyield
1244
+
1245
+ We expose `sys.Osyield`, to allow users to control the behavior of WASI's
1246
+ `sched_yield` without a new build of wazero. This is mainly for parity with
1247
+ all other related features which we allow users to implement, including
1248
+ `sys.Nanosleep`. Unlike others, we don't provide an out-of-box implementation
1249
+ primarily because it will cause performance problems when accessed.
1250
+
1251
+ For example, the below implementation uses CGO, which might result in a 1us
1252
+ delay per invocation depending on the platform.
1253
+
1254
+ See https://github.com/golang/go/issues/19409#issuecomment-284788196
1255
+ ```go
1256
+ //go:noescape
1257
+ //go:linkname osyield runtime.osyield
1258
+ func osyield()
1259
+ ```
1260
+
1261
+ In practice, a request to customize this is unlikely to happen until other
1262
+ thread based functions are implemented. That said, as of early 2023, there are
1263
+ a few signs of implementation interest and cross-referencing:
1264
+
1265
+ See https://github.com/WebAssembly/stack-switching/discussions/38
1266
+ See https://github.com/WebAssembly/wasi-threads#what-can-be-skipped
1267
+ See https://slinkydeveloper.com/Kubernetes-controllers-A-New-Hope/
1268
+
1269
+ ## sys.Stat_t
1270
+
1271
+ We expose `stat` information as `sys.Stat_t`, like `syscall.Stat_t` except
1272
+ defined without build constraints. For example, you can use `sys.Stat_t` on
1273
+ `GOOS=windows` which doesn't define `syscall.Stat_t`.
1274
+
1275
+ The first use case of this is to return inodes from `fs.FileInfo` without
1276
+ relying on platform-specifics. For example, a user could return `*sys.Stat_t`
1277
+ from `info.Sys()` and define a non-zero inode for a virtual file, or map a
1278
+ real inode to a virtual one.
1279
+
1280
+ Notable choices per field are listed below, where `sys.Stat_t` is unlike
1281
+ `syscall.Stat_t` on `GOOS=linux`, or needs clarification. One common issue
1282
+ not repeated below is that numeric fields are 64-bit when at least one platform
1283
+ defines it that large. Also, zero values are equivalent to nil or absent.
1284
+
1285
+ * `Dev` and `Ino` (`Inode`) are both defined unsigned as they are defined
1286
+ opaque, and most `syscall.Stat_t` also defined them unsigned. There are
1287
+ separate sections in this document discussing the impact of zero in `Ino`.
1288
+ * `Mode` is defined as a `fs.FileMode` even though that is not defined in POSIX
1289
+ and will not map to all possible values. This is because the current use is
1290
+ WASI, which doesn't define any types or features not already supported. By
1291
+ using `fs.FileMode`, we can re-use routine experience in Go.
1292
+ * `NLink` is unsigned because it is defined that way in `syscall.Stat_t`: there
1293
+ can never be less than zero links to a file. We suggest defaulting to 1 in
1294
+ conversions when information is not knowable because at least that many links
1295
+ exist.
1296
+ * `Size` is signed because it is defined that way in `syscall.Stat_t`: while
1297
+ regular files and directories will always be non-negative, irregular files
1298
+ are possibly negative or not defined. Notably sparse files are known to
1299
+ return negative values.
1300
+ * `Atim`, `Mtim` and `Ctim` are signed because they are defined that way in
1301
+ `syscall.Stat_t`: Negative values are time before 1970. The resolution is
1302
+ nanosecond because that's the maximum resolution currently supported in Go.
1303
+
1304
+ ### Why do we use `sys.EpochNanos` instead of `time.Time` or similar?
1305
+
1306
+ To simplify documentation, we defined a type alias `sys.EpochNanos` for int64.
1307
+ `time.Time` is a data structure, and we could have used this for
1308
+ `syscall.Stat_t` time values. The most important reason we do not is conversion
1309
+ penalty deriving time from common types.
1310
+
1311
+ The most common ABI used in `wasip2`. This, and compatible ABI such as `wasix`,
1312
+ encode timestamps in memory as a 64-bit number. If we used `time.Time`, we
1313
+ would have to convert an underlying type like `syscall.Timespec` to `time.Time`
1314
+ only to later have to call `.UnixNano()` to convert it back to a 64-bit number.
1315
+
1316
+ In the future, the component model module "wasi-filesystem" may represent stat
1317
+ timestamps with a type shared with "wasi-clocks", abstractly structured similar
1318
+ to `time.Time`. However, component model intentionally does not define an ABI.
1319
+ It is likely that the canonical ABI for timestamp will be in two parts, but it
1320
+ is not required for it to be intermediately represented this way. A utility
1321
+ like `syscall.NsecToTimespec` could split an int64 so that it could be written
1322
+ to memory as 96 bytes (int64, int32), without allocating a struct.
1323
+
1324
+ Finally, some may confuse epoch nanoseconds with 32-bit epoch seconds. While
1325
+ 32-bit epoch seconds has "The year 2038" problem, epoch nanoseconds has
1326
+ "The Year 2262" problem, which is even less concerning for this library. If
1327
+ the Go programming language and wazero exist in the 2200's, we can make a major
1328
+ version increment to adjust the `sys.EpochNanos` approach. Meanwhile, we have
1329
+ faster code.
1330
+
1331
+ ## poll_oneoff
1332
+
1333
+ `poll_oneoff` is a WASI API for waiting for I/O events on multiple handles.
1334
+ It is conceptually similar to the POSIX `poll(2)` syscall.
1335
+ The name is not `poll`, because it references [“the fact that this function is not efficient
1336
+ when used repeatedly with the same large set of handles”][poll_oneoff].
1337
+
1338
+ We chose to support this API in a handful of cases that work for regular files
1339
+ and standard input. We currently do not support other types of file descriptors such
1340
+ as socket handles.
1341
+
1342
+ ### Clock Subscriptions
1343
+
1344
+ As detailed above in [sys.Nanosleep](#sysnanosleep), `poll_oneoff` handles
1345
+ relative clock subscriptions. In our implementation we use `sys.Nanosleep()`
1346
+ for this purpose in most cases, except when polling for interactive input
1347
+ from `os.Stdin` (see more details below).
1348
+
1349
+ ### FdRead and FdWrite Subscriptions
1350
+
1351
+ When subscribing a file descriptor (except `Stdin`) for reads or writes,
1352
+ the implementation will generally return immediately with success, unless
1353
+ the file descriptor is unknown. The file descriptor is not checked further
1354
+ for new incoming data. Any timeout is cancelled, and the API call is able
1355
+ to return, unless there are subscriptions to `Stdin`: these are handled
1356
+ separately.
1357
+
1358
+ ### FdRead and FdWrite Subscription to Stdin
1359
+
1360
+ Subscribing `Stdin` for reads (writes make no sense and cause an error),
1361
+ requires extra care: wazero allows to configure a custom reader for `Stdin`.
1362
+
1363
+ In general, if a custom reader is found, the behavior will be the same
1364
+ as for regular file descriptors: data is assumed to be present and
1365
+ a success is written back to the result buffer.
1366
+
1367
+ However, if the reader is detected to read from `os.Stdin`,
1368
+ a special code path is followed, invoking `sysfs.poll()`.
1369
+
1370
+ `sysfs.poll()` is a wrapper for `poll(2)` on POSIX systems,
1371
+ and it is emulated on Windows.
1372
+
1373
+ ### Poll on POSIX
1374
+
1375
+ On POSIX systems, `poll(2)` allows to wait for incoming data on a file
1376
+ descriptor, and block until either data becomes available or the timeout
1377
+ expires.
1378
+
1379
+ Usage of `syfs.poll()` is currently only reserved for standard input, because
1380
+
1381
+ 1. it is really only necessary to handle interactive input: otherwise,
1382
+ there is no way in Go to peek from Standard Input without actually
1383
+ reading (and thus consuming) from it;
1384
+
1385
+ 2. if `Stdin` is connected to a pipe, it is ok in most cases to return
1386
+ with success immediately;
1387
+
1388
+ 3. `syfs.poll()` is currently a blocking call, irrespective of goroutines,
1389
+ because the underlying syscall is; thus, it is better to limit its usage.
1390
+
1391
+ So, if the subscription is for `os.Stdin` and the handle is detected
1392
+ to correspond to an interactive session, then `sysfs.poll()` will be
1393
+ invoked with a the `Stdin` handle *and* the timeout.
1394
+
1395
+ This also means that in this specific case, the timeout is uninterruptible,
1396
+ unless data becomes available on `Stdin` itself.
1397
+
1398
+ ### Select on Windows
1399
+
1400
+ On Windows `sysfs.poll()` cannot be delegated to a single
1401
+ syscall, because there is no single syscall to handle sockets,
1402
+ pipes and regular files.
1403
+
1404
+ Instead, we emulate its behavior for the cases that are currently
1405
+ of interest.
1406
+
1407
+ - For regular files, we _always_ report them as ready, as
1408
+ [most operating systems do anyway][async-io-windows].
1409
+
1410
+ - For pipes, we invoke [`PeekNamedPipe`][peeknamedpipe]
1411
+ for each file handle we detect is a pipe open for reading.
1412
+ We currently ignore pipes open for writing.
1413
+
1414
+ - Notably, we include also support for sockets using the [WinSock
1415
+ implementation of `poll`][wsapoll], but instead
1416
+ of relying on the timeout argument of the `WSAPoll` function,
1417
+ we set a 0-duration timeout so that it behaves like a peek.
1418
+
1419
+ This way, we can check for regular files all at once,
1420
+ at the beginning of the function, then we poll pipes and
1421
+ sockets periodically using a cancellable `time.Tick`,
1422
+ which plays nicely with the rest of the Go runtime.
1423
+
1424
+ ### Impact of blocking
1425
+
1426
+ Because this is a blocking syscall, it will also block the carrier thread of
1427
+ the goroutine, preventing any means to support context cancellation directly.
1428
+
1429
+ There are ways to obviate this issue. We outline here one idea, that is however
1430
+ not currently implemented. A common approach to support context cancellation is
1431
+ to add a signal file descriptor to the set, e.g. the read-end of a pipe or an
1432
+ eventfd on Linux. When the context is canceled, we may unblock a Select call by
1433
+ writing to the fd, causing it to return immediately. This however requires to
1434
+ do a bit of housekeeping to hide the "special" FD from the end-user.
1435
+
1436
+ [poll_oneoff]: https://github.com/WebAssembly/wasi-poll#why-is-the-function-called-poll_oneoff
1437
+ [async-io-windows]: https://tinyclouds.org/iocp_links
1438
+ [peeknamedpipe]: https://learn.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-peeknamedpipe
1439
+ [wsapoll]: https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll
1440
+
1441
+ ## Signed encoding of integer global constant initializers
1442
+
1443
+ wazero treats integer global constant initializers signed as their interpretation is not known at declaration time. For
1444
+ example, there is no signed integer [value type](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#value-types%E2%91%A0).
1445
+
1446
+ To get at the problem, let's use an example.
1447
+ ```
1448
+ (global (export "start_epoch") i64 (i64.const 1620216263544))
1449
+ ```
1450
+
1451
+ In both signed and unsigned LEB128 encoding, this value is the same bit pattern. The problem is that some numbers are
1452
+ not. For example, 16256 is `807f` encoded as unsigned, but `80ff00` encoded as signed.
1453
+
1454
+ While the specification mentions uninterpreted integers are in abstract [unsigned values](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#integers%E2%91%A0),
1455
+ the binary encoding is clear that they are encoded [signed](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#integers%E2%91%A4).
1456
+
1457
+ For consistency, we go with signed encoding in the special case of global constant initializers.
1458
+
1459
+ ## Implementation limitations
1460
+
1461
+ WebAssembly 1.0 (20191205) specification allows runtimes to [limit certain aspects of Wasm module or execution](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#a2-implementation-limitations).
1462
+
1463
+ wazero limitations are imposed pragmatically and described below.
1464
+
1465
+ ### Number of functions in a module
1466
+
1467
+ The possible number of function instances in [a module](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#module-instances%E2%91%A0) is not specified in the WebAssembly specifications since [`funcaddr`](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-funcaddr) corresponding to a function instance in a store can be arbitrary number.
1468
+ wazero limits the maximum function instances to 2^27 as even that number would occupy 1GB in function pointers.
1469
+
1470
+ That is because not only we _believe_ that all use cases are fine with the limitation, but also we have no way to test wazero runtimes under these unusual circumstances.
1471
+
1472
+ ### Number of function types in a store
1473
+
1474
+ There's no limitation on the number of function types in [a store](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#store%E2%91%A0) according to the spec. In wazero implementation, we assign each function type to a unique ID, and choose to use `uint32` to represent the IDs.
1475
+ Therefore the maximum number of function types a store can have is limited to 2^27 as even that number would occupy 512MB just to reference the function types.
1476
+
1477
+ This is due to the same reason for the limitation on the number of functions above.
1478
+
1479
+ ### Number of values on the stack in a function
1480
+
1481
+ While the the spec does not clarify a limitation of function stack values, wazero limits this to 2^27 = 134,217,728.
1482
+ The reason is that we internally represent all the values as 64-bit integers regardless of its types (including f32, f64), and 2^27 values means
1483
+ 1 GiB = (2^30). 1 GiB is the reasonable for most applications [as we see a Goroutine has 250 MB as a limit on the stack for 32-bit arch](https://github.com/golang/go/blob/go1.24.0/src/runtime/proc.go#L154-L161), considering that WebAssembly is (currently) 32-bit environment.
1484
+
1485
+ All the functions are statically analyzed at module instantiation phase, and if a function can potentially reach this limit, an error is returned.
1486
+
1487
+ ### Number of globals in a module
1488
+
1489
+ Theoretically, a module can declare globals (including imports) up to 2^32 times. However, wazero limits this to 2^27(134,217,728) per module.
1490
+ That is because internally we store globals in a slice with pointer types (meaning 8 bytes on 64-bit platforms), and therefore 2^27 globals
1491
+ means that we have 1 GiB size of slice which seems large enough for most applications.
1492
+
1493
+ ### Number of tables in a module
1494
+
1495
+ While the the spec says that a module can have up to 2^32 tables, wazero limits this to 2^27 = 134,217,728.
1496
+ One of the reasons is even that number would occupy 1GB in the pointers tables alone. Not only that, we access tables slice by
1497
+ table index by using 32-bit signed offset in the compiler implementation, which means that the table index of 2^27 can reach 2^27 * 8 (pointer size on 64-bit machines) = 2^30 offsets in bytes.
1498
+
1499
+ We _believe_ that all use cases are fine with the limitation, but also note that we have no way to test wazero runtimes under these unusual circumstances.
1500
+
1501
+ If a module reaches this limit, an error is returned at the compilation phase.
1502
+
1503
+ ## Compiler engine implementation
1504
+
1505
+ ### Why it's safe to execute runtime-generated machine codes against async Goroutine preemption
1506
+
1507
+ Goroutine preemption is the mechanism of the Go runtime to switch goroutines contexts on an OS thread.
1508
+ There are two types of preemption: cooperative preemption and async preemption. The former happens, for example,
1509
+ when making a function call, and it is not an issue for our runtime-generated functions as they do not make
1510
+ direct function calls to Go-implemented functions. On the other hand, the latter, async preemption, can be problematic
1511
+ since it tries to interrupt the execution of Goroutine at any point of function, and manipulates CPU register states.
1512
+
1513
+ Fortunately, our runtime-generated machine codes do not need to take the async preemption into account.
1514
+ All the assembly codes are entered via the trampoline implemented as Go Assembler Function (e.g. [arch_amd64.s](./arch_amd64.s)),
1515
+ and as of Go 1.20, these assembler functions are considered as _unsafe_ for async preemption:
1516
+ - https://github.com/golang/go/blob/go1.24.0/src/runtime/preempt.go#L407-L408
1517
+ - https://github.com/golang/go/blob/go1.24.0/src/runtime/traceback.go#L350
1518
+
1519
+ From the Go runtime point of view, the execution of runtime-generated machine codes is considered as a part of
1520
+ that trampoline function. Therefore, runtime-generated machine code is also correctly considered unsafe for async preemption.
1521
+
1522
+ ## Why context cancellation is handled in Go code rather than native code
1523
+
1524
+ Since [wazero v1.0.0-pre.9](https://github.com/tetratelabs/wazero/releases/tag/v1.0.0-pre.9), the runtime
1525
+ supports integration with Go contexts to interrupt execution after a timeout, or in response to explicit cancellation.
1526
+ This support is internally implemented as a special opcode `builtinFunctionCheckExitCode` that triggers the execution of
1527
+ a Go function (`ModuleInstance.FailIfClosed`) that atomically checks a sentinel value at strategic points in the code.
1528
+
1529
+ [It _is indeed_ possible to check the sentinel value directly, without leaving the native world][native_check], thus sparing some cycles;
1530
+ however, because native code never preempts (see section above), this may lead to a state where the other goroutines
1531
+ never get the chance to run, and thus never get the chance to set the sentinel value; effectively preventing
1532
+ cancellation from taking place.
1533
+
1534
+ [native_check]: https://github.com/tetratelabs/wazero/issues/1409
1535
+
1536
+ ## Golang patterns
1537
+
1538
+ ### Hammer tests
1539
+ Code that uses concurrency primitives, such as locks or atomics, should include "hammer tests", which run large loops
1540
+ inside a bounded amount of goroutines, run by half that many `GOMAXPROCS`. These are named consistently "hammer", so
1541
+ they are easy to find. The name inherits from some existing tests in [golang/go](https://github.com/golang/go/search?q=hammer&type=code).
1542
+
1543
+ Here is an annotated description of the key pieces of a hammer test:
1544
+ 1. `P` declares the count of goroutines to use, defaulting to 8 or 4 if `testing.Short`.
1545
+ * Half this amount are the cores used, and 4 is less than a modern laptop's CPU. This allows multiple "hammer" tests to run in parallel.
1546
+ 2. `N` declares the scale of work (loop) per goroutine, defaulting to value that finishes in ~0.1s on a modern laptop.
1547
+ * When in doubt, try 1000 or 100 if `testing.Short`
1548
+ * Remember, there are multiple hammer tests and CI nodes are slow. Slower tests hurt feedback loops.
1549
+ 3. `defer runtime.GOMAXPROCS(runtime.GOMAXPROCS(P/2))` makes goroutines switch cores, testing visibility of shared data.
1550
+ 4. To ensure goroutines execute at the same time, block them with `sync.WaitGroup`, initialized to `Add(P)`.
1551
+ * `sync.WaitGroup` internally uses `runtime_Semacquire` not available in any other library.
1552
+ * `sync.WaitGroup.Add` with a negative value can unblock many goroutines at the same time, e.g. without a for loop.
1553
+ 5. Track goroutines progress via `finished := make(chan int)` where each goroutine in `P` defers `finished <- 1`.
1554
+ 1. Tests use `require.XXX`, so `recover()` into `t.Fail` in a `defer` function before `finished <- 1`.
1555
+ * This makes it easier to spot larger concurrency problems as you see each failure, not just the first.
1556
+ 2. After the `defer` function, await unblocked, then run the stateful function `N` times in a normal loop.
1557
+ * This loop should trigger shared state problems as locks or atomics are contended by `P` goroutines.
1558
+ 6. After all `P` goroutines launch, atomically release all of them with `WaitGroup.Add(-P)`.
1559
+ 7. Block the runner on goroutine completion, by (`<-finished`) for each `P`.
1560
+ 8. When all goroutines complete, `return` if `t.Failed()`, otherwise perform follow-up state checks.
1561
+
1562
+ This is implemented in wazero in [hammer.go](internal/testing/hammer/hammer.go)
1563
+
1564
+ ### Lock-free, cross-goroutine observations of updates
1565
+
1566
+ How to achieve cross-goroutine reads of a variable are not explicitly defined in https://go.dev/ref/mem. wazero uses
1567
+ atomics to implement this following unofficial practice. For example, a `Close` operation can be guarded to happen only
1568
+ once via compare-and-swap (CAS) against a zero value. When we use this pattern, we consistently use atomics to both
1569
+ read and update the same numeric field.
1570
+
1571
+ In lieu of formal documentation, we infer this pattern works from other sources (besides tests):
1572
+ * `sync.WaitGroup` by definition must support calling `Add` from other goroutines. Internally, it uses atomics.
1573
+ * rsc in golang/go#5045 writes "atomics guarantee sequential consistency among the atomic variables".
1574
+
1575
+ See https://github.com/golang/go/blob/go1.24.0/src/sync/waitgroup.go#L76
1576
+ See https://github.com/golang/go/issues/5045#issuecomment-252730563
1577
+ See https://www.youtube.com/watch?v=VmrEG-3bWyM