wasmtime::component::bindgen: How to specify a resource in "imports:"?

[tliron]

In the documentation here there are examples of imported interfaces, but not of resources in the interfaces.

Specificaly I want to mark only the resource as async. I've tried various notations to no avail.

Given this world:

package floria:plugins;

world dispatch-plugin {
    import floria;
}

interface floria {
    resource session {
        constructor();
        get-entity: func(id: string) -> result<string, string>;
    }

Here are my bindings:

wasmtime::component::bindgen!({
    path: "assets/wit/floria-plugins.wit",
    imports: {
        // "floria:plugins/floria.session": async | trappable,
        default: trappable,
    }
});

The commented-out line is one of my attempts. :) However, I get errors such as this:

unused `imports` rules found: ["\"floria:plugins/floria.session\": FunctionFlags(ASYNC | TRAPPABLE)"]

What is the correct notation for referring to resources in imports? Is it even possible?

Note that I truncated the WIT file here. In fact I have many more imports, which I do not want to be async.

[alexcrichton]

The syntax currently looks like this, aka floria:plugins/floria.[method]session.get-entity I believe. Good call out though for this being missing in our documentation, this is definitely something we should showcase in examples.

[tliron]

Interesting! I would never have guessed. :)

It seems like there exists a concept of a "WIT path". Perhaps it deserved documentation on its own page?

Also, is there a way I can match the entire resource? I tried floria:plugins/floria.[method]session, but it gives an error.

[tliron]

Well, I got things to compile, but not to run. :/

Having any async import means that I now have to call bindings::DispatchPlugin::instantiate_async instead of bindings::DispatchPlugin::instantiate. That's fine, but it has cascading effects. I am getting these errors when trying to call (non-async) exports (not imports):

store configuration requires that `*_async` functions are used instead

Is it even possible to have only some imports be async?

[alexcrichton]

For a "WIT Path", sort of yeah, although it's not an official concept and just a convention for Wasmtime. Definitely worth documenting I agree, and the documentation spot you linked, or the examples, is where it'd go.

For matching an entire resource, unfortunately not right now. You'll have to list out each method individually.

For the error you're seeing, that's expected yeah. Synchronous imports can still call host-async functions, and there's no way to prevent it, so once something async is added to the store async invocations are required everywhere.

[tliron]

I think I understand. But isn't the implication, then, that you must mark all imports as async if you mark one as async? In other words, the only working use case would be default: async. If that's true, then the documentation is misleading. It's technically correct in that you can mark individual functions as async, but that doesn't lead to anything functional.

I think it would be better if the async example made this clear.

[alexcrichton]

Ah sorry, other way around. Imports can be a mixture of async/sync as desired, but if any import is sync async then all exports must be async.

[tliron]

but if any import is sync then all exports must be async

Do you mean: "if any import is async then all exports must be async"?

If so, then shouldn't the bindgen! macro handle this? If any import is async, then exports should automatically have default: async. Otherwise we get errors in runtime and confusion like I am experiencing. ;) (Of course, I would suggest that all of this needs to be documented!)

[alexcrichton]

Er, sorry, yes! (updated above)

And, yes, that's possible to handle in bindgen! yeah. That might be more of an error at bindgen! time rather than auto-switch-to-async as while it may reduce confusion for you it may increase confusion for others when things start popping up async without being specified async. And, yeah, definitely agreed that docs could be improved here.

[tliron]

Phew, OK! I do suggest adding a tag other than "documentation" to this issue. Let me try to summarize the task:

Code fix for bindgen macro:

• If there is any import function marked async, check to see if all exports are also async. If this is not the case, emit an error, preferably with a link to documentation (see below).

Documentation fix for bindgen macro:

• Explain the rule above in the comment above "imports". (It would actually be nice if someone with some knowledge of the implementation could explain why this rule exists.)

Documentation fixes for async example:

1. The documentation links to an outdated p1 example. It should probably point to https://github.com/bytecodealliance/wasmtime/blob/main/examples/wasip2-async/main.rs instead.
2. The documentation should include the main function from the example code (the other examples do this). Here it is especially important because it highlights that instantiate_async must be called instead of instantiate. (This should be noted and explained in a code comment.) EDIT: there are other _async variants that are required, too. Such as Resource::resource_drop_async.
3. The async example should remind readers of the bindgen rule above, perhaps link to the relevant documentation. This can be added as code documentation in the this WIT.

EDIT: For what it's worth, following this rule got everything to work on my end! :)