Repository navigation
feat: generate a typed async client for a Teal module from [rust] exports (#538) - #559
Merged
Merged
Conversation
…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
This was referenced Oct 25, 2026
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
The second half of #538, on top of
htl::run(#558): Rust clients generated from a Teal module's declared functions.htl.tomlgains[rust] exports = ["<module>", ...](crates/htl-core/src/config.rs).htl rsandteal_types!()build onersgen::Specfrom the config (Spec::from(&RustConfig)) and call the samersgen::generate, so the filehtl rswrites and the items the macro expands to are the same text.rsgenwrites a client named after the record the module returns (local record app→App;local record M→M, told apart by module path) in the samepub modtree as the data types:load(runner, extra_paths),instance(), and oneasyncmethod per function-typed field declared in the record body. Each method converts and calls on the runner (Instance::call) and returnsResult<_, htl::run::CallError>.htl rsalready uses for data; two or more results are a tuple. A parameter isOption<T>only when its Teal type isT | nil; every other parameter isT.anyand any record that reachesanydirectly or through other records (anmlua::Valueis notSend), more than 16 parameters or results (mlua's tuple limit), a function namedload,instance,cloneorclone_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.function M.f() ... end), which the type index keeps no type for, with how to bring it in (declaref: function(..)in the body).crates/htl-core/src/rsgen/client.rs; the generated struct's doc says it needs htl'sasyncfeature.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:
Optionfrom 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 madefunction(a?: string, b: integer)a client whosebisOption<i64>, so a host'sNonewould reach Teal'sintegeras nil. Mapping every parameter toTis 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.any, more than 16 values, and names that would shadowClone.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.stderrsnapshots (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.
[rust] exports = ["m"]on a module declaringf: function(string, ? integer): string, integermakesteal_types!()expand tom::M::f(&self, a1: String, a2: Option<i64>) -> Result<(String, i64), htl::run::CallError>, and passing ani64asa1is a compile error.a2: i64: the design review found theOptionunsound (What changed). AT | nilparameter is the one that becomesOption<T>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>andpub async fn greet(&self, a1: ::std::string::String, a2: ::core::option::Option<::std::string::String>) -> ::core::result::Result<super::types::Output, ::htl::run::CallError>forgreet: function(string, string | nil): types.Output.rsgentest:function(a?: string, b: integer)givesa1: String, a2: i64. e2eteal_exports_client: the correct calls build and the binary printsabc 3andtrue Dr. Ada;app.split(42)makescargo check --message-format=jsonreport the error codes["E0308"][rust] exportsdid not exist;htl.tomlrefused the keyhtl rswrites the same text asteal_types!()expands to.htl-clirs_cli: thehtl rsbinary'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.rscompiles that golden againsthtl::runand calls it (two-result tuple,TealRecordresult,Some/Nonefor theT | nilparameter, fromtokio::spawn)Checks
rsgenunit tests (golden, each problem, exports order and duplicates, the review's regressions); 2 inhtl-clirs_cliand 2 inhtl-macros;crates/htl/tests/run_client.rs; e2eteal_exports_client; the "nothing to write" message now namesmodules and exports.just pre-commit(fmt, tests, clippy):cargo fmt --all --checkclean,cargo test --workspace1689 passed / 0 failed,cargo clippy --workspace --all-targets0 warnings.just pre-push(full build, end-to-end cases): passed (exit 0), includingteal_exports_client.e2e/tests/teal_exports_client.rs(new).htl(the change is in the generator, which the CLI runs throughhtl rs, covered by thers_clitest on the built binary). Run on a dogfood project instead: a host of about 2,250 lines of Teal and a 107-line Rustmainthat loads its client throughteal_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.rsgenmodule doc's Exports section (mapping, problems, notes);[rust] exportsinconfig.rs;htl rshelp and doc;teal_types!doc.Unintended changes
The message
htl rsprints 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
a1, a2, ...(typeindex: keep parameter names in FnSig #557), and a?parameter is required from Rust (same issue).[rust.types]that holds anmlua::Valueis not refused by the generator; rustc stops it.modulesandexportsis lowered twice (cost only); the e2e helpers are a third copy of the ones in two other e2e files; the detection ofanyuses a side channel that callers clear; the fixpoint over records is quadratic in the number of records.Refs #538