Skip to content

feat: generate a typed async client for a Teal module from [rust] exports (#538) - #559

Merged
ynishi merged 1 commit into
mainfrom
feat/538-exports
Oct 25, 2026
Merged

ynishi merged 1 commit into
mainfrom
feat/538-exports

Conversation

@ynishi

@ynishi ynishi commented Oct 25, 2026

Copy link
Copy Markdown
Owner

What changed

The second half of #538, on top of htl::run (#558): Rust clients generated from a Teal module's declared functions.

  • htl.toml gains [rust] exports = ["<module>", ...] (crates/htl-core/src/config.rs). htl rs and teal_types!() build one rsgen::Spec from the config (Spec::from(&RustConfig)) and call the same rsgen::generate, so the file htl rs writes and the items the macro expands to are the same text.
  • For each listed module, rsgen writes a client named after the record the module returns (local record app → App; local record M → M, told apart by module path) in the same pub mod tree as the data types: load(runner, extra_paths), instance(), and one async method per function-typed field declared in the record body. Each method converts and calls on the runner (Instance::call) and returns Result<_, htl::run::CallError>.
  • Parameter and result types use the mapping htl rs already uses for data; two or more results are a tuple. A parameter is Option<T> only when its Teal type is T | nil; every other parameter is T.
  • Refused at the Teal line, writing nothing (as for data): a method, a generic, a variadic parameter or result, an overload, any and any record that reaches any directly or through other records (an mlua::Value is not Send), more than 16 parameters or results (mlua's tuple limit), a function named load, instance, clone or clone_from, a name that is no Rust name, a module that returns no record, a client name that clashes with a type or child module.
  • Notes, not failures: a record that declares no function, and each function defined outside the record body (function M.f() ... end), which the type index keeps no type for, with how to bring it in (declare f: function(..) in the body).
  • The client lowering is a child module, crates/htl-core/src/rsgen/client.rs; the generated struct's doc says it needs htl's async feature.
  • README: a section on calling Teal from async Rust.

Why this shape: it ports a prototype that ran a host whose logic lives in Teal (below) and was reviewed against the design. Two choices differ from the prototype and from the issue's proposed criterion 1, both from the design review:

  • No Option from the required-parameter count. FnSig.required (typeindex: keep a function's signature in TypeExpr::Fn #553) is how many parameters are required, not which; reading positions from the count made function(a?: string, b: integer) a client whose b is Option<i64>, so a host's None would reach Teal's integer as nil. Mapping every parameter to T is sound (the host always passes a value); the cost is that a ? parameter cannot be left out from Rust. Which parameters are optional is read from source, like parameter names, so it goes with typeindex: keep parameter names in FnSig #557.
  • The generator refuses what would not compile, rather than leaving it to rustc: records reaching any, more than 16 values, and names that would shadow Clone.

Rejected: a trait-based client a test could fake (wider scope, no criterion needs it); documenting Instance::call::<A, R>("f", args) instead of generating (the argument types would not be checked); waiting for #557 (names can be added later without breaking positional calls); testing the compile error with trybuild .stderr snapshots (stable and the 1.88 MSRV word rustc's errors differently).

Acceptance

Criteria 1 and 4 of the proposed acceptance in the #538 comment (2 and 3 were met by #558). Expected values were written from the criteria before running.

# Criterion (quoted from the issue) Expected Actual Fails before
1 [rust] exports = ["m"] on a module declaring f: function(string, ? integer): string, integer makes teal_types!() expand to m::M::f(&self, a1: String, a2: Option<i64>) -> Result<(String, i64), htl::run::CallError>, and passing an i64 as a1 is a compile error. as quoted, except a2: i64: the design review found the Option unsound (What changed). A T | nil parameter is the one that becomes Option<T> Golden (crates/htl-core/tests/fixtures/client/teal_types.rs): pub async fn split(&self, a1: ::std::string::String) -> ::core::result::Result<(::std::string::String, i64), ::htl::run::CallError> and pub async fn greet(&self, a1: ::std::string::String, a2: ::core::option::Option<::std::string::String>) -> ::core::result::Result<super::types::Output, ::htl::run::CallError> for greet: function(string, string | nil): types.Output. rsgen test: function(a?: string, b: integer) gives a1: String, a2: i64. e2e teal_exports_client: the correct calls build and the binary prints abc 3 and true Dr. Ada; app.split(42) makes cargo check --message-format=json report the error codes ["E0308"] n/a: [rust] exports did not exist; htl.toml refused the key
4 htl rs writes the same text as teal_types!() expands to. both equal one golden for one fixture htl-cli rs_cli: the htl rs binary's file on the fixture equals the golden; htl-macros: the expansion of the same fixture equals the same golden; crates/htl/tests/run_client.rs compiles that golden against htl::run and calls it (two-result tuple, TealRecord result, Some/None for the T | nil parameter, from tokio::spawn) n/a, as above

Checks

  • Tests added or changed: 23 rsgen unit tests (golden, each problem, exports order and duplicates, the review's regressions); 2 in htl-cli rs_cli and 2 in htl-macros; crates/htl/tests/run_client.rs; e2e teal_exports_client; the "nothing to write" message now names modules and exports.
  • just pre-commit (fmt, tests, clippy): cargo fmt --all --check clean, cargo test --workspace 1689 passed / 0 failed, cargo clippy --workspace --all-targets 0 warnings.
  • just pre-push (full build, end-to-end cases): passed (exit 0), including teal_exports_client.
  • End-to-end cases added or changed: e2e/tests/teal_exports_client.rs (new).
  • Run through the installed binary on a project (CONTRIBUTING.md, Verification): not with an installed htl (the change is in the generator, which the CLI runs through htl rs, covered by the rs_cli test on the built binary). Run on a dogfood project instead: a host of about 2,250 lines of Teal and a 107-line Rust main that loads its client through teal_types!() with [rust] exports, built against this branch: its output over 6 scenarios and its plan are byte-identical to a reference written by the earlier all-Rust version of the same tool, and a policy hook that loops forever is cut at the 5 s deadline.
  • Docs updated (README, doc comments): README section; the rsgen module doc's Exports section (mapping, problems, notes); [rust] exports in config.rs; htl rs help and doc; teal_types! doc.

Unintended changes

The message htl rs prints when there is nothing to write changed from ([rust] modules is empty) to ([rust] modules and exports are empty). Intended: either list now produces output.

Not covered

Refs #538

…ports` (#538)

`htl.toml` `[rust] exports = ["<module>"]` makes `htl rs` and `teal_types!()` write, for each listed module, a typed async client over `htl::run`. This is the second half of #538; the first half, `htl::run`, is the runner this client sits on. Both entry points build their spec the same way, `Spec::from(&RustConfig)`, and call the same `rsgen::generate`, so the CLI and the macro cannot disagree about what a module exports.

Shape of the client:

- The struct is named after the record the module returns: `app` gives `App`, and `M` stays `M`.
- `load(runner, extra_paths)` requires the module on a runner and `instance()` gives the loaded instance back. Each declared function becomes one async method.
- A method is made for each function-typed field declared in the record body. Parameters and results go through the same type table as the data types. Two or more results come back as a tuple.
- A parameter is `T`, and `Option<T>` only when the Teal type is `T | nil`. The type index keeps a count of required parameters, not which ones, so that count is not used: an optional `?` parameter is required in Rust. Per-parameter marks belong with #557.
- Arguments are named `a1, a2, ...` until #557 gives them names.
- The generated struct's doc says it needs htl's `async` feature.

What `generate` refuses, as a problem reported at the Teal line of the field or the module:

- a method, a generic function, a variadic parameter or result, an overload
- `any`, and any record that reaches `any` transitively, computed from the lowered records
- more than 16 parameters or results, which is mlua's tuple limit
- the names `load`, `instance`, `clone` and `clone_from`, which the client's own items use
- a name that is no Rust name, and two names that clash
- a module that returns no record

Two cases are notes and not failures: a record that declares no function, and a function defined outside the record body (`function M.f`), for which the index keeps no type. The rules are in the Exports section of the `rsgen` module doc.

The client lowering lives in `rsgen/client.rs`, so `rsgen.rs` only gains the part that decides which modules to lower and where the problems go. `config.rs` gains the `exports` key. The README gains a section on the client.

Tests:

- `rsgen` unit tests: a golden for the client, one case per problem above, the order and duplicates of `exports`, and the regressions found in review.
- A shared fixture and golden under `crates/htl-core/tests/fixtures/client`, compared byte for byte by `htl-macros` (the expansion) and by `htl-cli` (`htl rs`), so the two entry points are held to one output.
- `crates/htl/tests/run_client.rs`: the golden is compiled and called on a real runner.
- `e2e/tests/teal_exports_client.rs`: a correct call builds and runs; a call with a wrong argument type makes `cargo check --message-format=json` report error code E0308.

Refs #538
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant