feat(server): Add support for async server function, module.server, and express module

[mconflitti-pbc]

Coming across a use case using chatlas where I need to be able to await an async function in my server function but shiny does not currently support this.

Simple addition to _session.py to handle both sync and async.

[schloerke]

Is your use case for setting up data? When are you needing the result of the information? (I guess, can you give a tiny motivation example that chatlas would use?)

Why not put it behind an async reactive calculation? Then the value can be used accordingly.

Ex:

From

async def server(input):
    data = await get_data()

to

def server(input):

    @reactive.calc
    async def data():
        return await get_data()

[mconflitti-pbc]

Is your use case for setting up data? When are you needing the result of the information? (I guess, can you give a tiny motivation example that chatlas would use?)

Why not put it behind an async reactive calculation? Then the value can be used accordingly.

Ex:

From

async def server(input):
    data = await get_data()

to

def server(input):

    @reactive.calc
    async def data():
        return await get_data()

Inside of chatlas, the server function is defined for you and I want to be able to access the session headers to get the user session token when using chat.app()

in chat.app()

  async def server(input, output, session):  # noqa: A002
      if session_callback:
          await session_callback(session)

May be too niche of a problem, but was surprised to see shiny didnt support both. And afaict, no reason that it can't.

[schloerke]

Because this can be defined with an async function, can we use wrap_async when storing the fn value below?

This will always upgrade the function to async. Then in _session.py, we will always await the server execution as the run method is already an async method.

[schloerke]

The current cast calls are lying as to what values are already there. Please update them accordingly.

By wrapping all server functions to be async, we won't need to check if we need to await or not (as we'll always need to await).

[mconflitti-pbc]

Sweet. Makes sense to me.

[mconflitti-pbc]

Though, now looking into support server function to be async, would need to go down the rabbit hole of ensure that we tackle other side effects like the module.server() decorator which is not async. Could leave it only supporting sync i suppose.. curious on thoughts from @wch.

[schloerke]

Happy to have all server-like functions upgraded to async

[wch]

I agree with @schloerke - it makes sense to make everything async-capable. Hopefully that's not too much more work.

[schloerke]

was surprised to see shiny didnt support both. And afaict, no reason that it can't.

Fair!

[schloerke]

Cosmetic split.

Suggested change

	Callable[[Inputs], Awaitable[None] | None]
	| Callable[[Inputs, Outputs, Session], Awaitable[None] | None]
	Callable[[Inputs], None]
	| Callable[[Inputs, Outputs, Session], None]
	| Callable[[Inputs], Awaitable[None]]
	| Callable[[Inputs, Outputs, Session], Awaitable[None]]

I remember something from past return types that it's a little better to split Awaitable from the return type as it can't actually return both, but it is really two independent types.

[wch]

Agreed, they are different types and need separate entries for correctness.

[wch]

Instead of adding this function, can we change is_async_callable() to a TypeIs?

[wch]

I just saw the comment below about how TypeIs didn't work. Can you add a comment explaining the problem? Otherwise we'll keep coming back to this and asking TypeIs in the future.

[wch]

I think the change on this line shouldn't be necessary, after making the changes above in the signature of __init__.

I could be wrong, but I don't believe it's possible for a function in Python to have a return value of Awaitable[R] | R.

[wch]

Is this change necessary?

[wch]

I wonder if there's a way to define a generic that handles the sync/async function cases. I asked Claude and it gave me something, but it will require a closer look to make sure it's right, and perhaps it should go in a separate PR that puts it in types.py.

from typing import TypeVar, Awaitable, Protocol, Callable, Union, ParamSpec, cast, overload

# Define a covariant TypeVar for the return type
R_co = TypeVar('R_co', covariant=True)

# Define a parameter specification for flexible argument handling
P = ParamSpec('P')

# More descriptive type alias
MaybeAwaitableCallable = Union[
    Callable[P, R_co],
    Callable[P, Awaitable[R_co]]
]

async def wrap(fn: MaybeAwaitableCallable[P, None], *args: P.args, **kwargs: P.kwargs) -> int:
    # Implementation remains the same
    result = fn(*args, **kwargs)
    # Note: We would use is_async_callable() instead of isinstance()
    if isinstance(result, Awaitable):
        await result
    return 42


## Example usage

def sync_function(a: int, b: str) -> None:
    print(f"Sync: {a}, {b}")

async def async_function(a: int, b: str) -> None:
    print(f"Async: {a}, {b}")


async def test() -> None:
    # Both of these are valid
    await wrap(sync_function, 1, "test")
    await wrap(async_function, 2, "async")