Server functions

[matthewp]

Idea dropped due to constraints that can't be overcome. See the comments 👇

Body

Summary

It would be great if you could pass a function to a client component by reference. The function would exist on the server and the client could call it; effectively an RPC.

Background & Motivation

Inspired by the recent implementation of "server functions" in the JS ecosystem, I think Astro could do something even better, with fewer of the downsides of server functions elsewhere.

With server functions you write a function in client code that runs on the server. This means you can't access variables within the closure of the function. Some frameworks do "scope copying", which serializes the scope and passes it to the RPC call. This only works with serializable variables and can be expensive to serialize a large closure.

Since Astro is server-first, we could simply pass a function; the actual function with its real closure, to the client as a reference.

Goals

• Allow passing arbitrary functions to client components, as references.
• Have full access to the function's closure, as it is the real function and not a compiled look-alike.
• Do this in a memory safe way.

Example

---
import TodoApp from '../components/TodoApp.jsx';
import db from 'some-db';

const sessionId = Astro.cookies.get('sessionid');

const saveTodo = async todo => {
  const userId = await getUserFromSession(sessionId);
  await db.insert('todos', { userId, ...todo });
  return {
    ok: true,
  };
};
---

<TodoApp saveTodo={saveTodo} client:load />

[matthewp]

Note that this would have to be an SSR-only feature.

[natemoo-re]

I've wanted this for a long time, this would be huge! I have never wrapped my brain around exactly how this would work, but I'd be really pumped about a proof-of-concept here.

[wassfila]

interesting, would it be possible to explain how this would execute ? Would Astro then automaticaly create an API endpoint, and generate client script for the post and return the result ? Would that API endpoint be protected from being called by other functions or beyond ?

[wassfila]

just started thinking about it, I guess the existing RPC clients integrations might be a good start, cause this is pretty much it 95%
Memory leaks do not seem more relevant than in other end point use cases (user problem) plus Serverless won't let them happen ;)
This looks like a powerful feature that can give Astro a great advantage, I made plenty of server/client state usage patterns, and this would save a lot of overhead

[matthewp]

I'm glad you brought up serverless. That actually kind of ruins this idea. You can't retain memory in serverless. :(

[wassfila]

I'm not sure I really could understand the non feasibility in serverless. I might have brought serverless by luck, in the intention that Serverless is stateless, in the meaning, after a while, it reruns again like if the server has restarted, which makes it immune to long term memory leaks.
But I don't really get the link between your proposal and the memory usage how it could prevent it. You can't count on retaining memory, true, but you can retain code.
It feels to me that if an API Endpoint is possible, this Server Function should be possible too, or at least that path should be explored.
Also if memory is recreated on every request call, it's always there.

[LopezNoah]

I think maybe serverless would be a problem if the functions are stored in a Promise map? The result of that promise won't be retained. Otherwise, I don't think its an issue to use an API endpoint. Existing RPC libraries seem like they accomplish this.

---

If a function is defined in the route (like in the first example), you'd need to store that endpoint somewhere. A function could be defined outside of the component and imported in:

---
import TodoApp from '../components/TodoApp.jsx';
import { saveTodo } from '../actions/saveTodo';
import db from 'some-db';

---

<TodoApp saveTodo={saveTodo} client:load />

In this case, I still think that function deserves an endpoint. Creating an endpoint like RPC libraries would just mean we point to one area and use it everywhere. This way the server can use functions on Astro components, pages, layouts, etc. Not sure how you'd scope it without endpoints unless you let a component return early and cancel streaming.

[matthewp]

@LopezNoah Presumably actions/ is a special folder and we set up routes for them? If so then yes! That could be an alternative. That is a different enough proposal though, and deserves its own place.

[LopezNoah]

I was just thinking about this after I saw it in the Remix discussions: Defining loaders and actions anywhere in the module graph. I saw Ryan Florence's comment where he said:

Similarly, this will hoist the actions to the internal route action and replace the call sites with URLs, maybe something like <form action="/this/route?__action={someId}">.

I experimented with creating the ActionFunction and LoaderFunction types similar to Remix and got pretty lucky. The LoaderFunction is basically the equivalent to Astro's frontmatter in each .astro file, but the actions are new. I created some actions and was able to trigger them on POST requests, but they still have to return HTML/the rendered Astro components. The map idea mentioned above was something I considered as well since you could have multiple actions in a single route or component.

While I was able to return a single rendered Astro component from a route, I'd rather return a JSON response rather than HTML. It's convenient to return HTML if you're using something like HTMX where you'd be swapping in HTML into the DOM anyways. Most developer's consumers of the data would be Typescript components anyways (imo).

At my workplace, we currently use a CMS that relies on postbacks to update pages (using ASP.NET 4.7.2), but our vendor plans to upgrade to Vue and API endpoints in the future. I think it's highly beneficial to co-locate the block components and their actions in the same space. If Astro components could have actions independent of the routes while still mapping to the route it would be a game-changer!

[matthewp]

Dropping this proposal after @wassfila brought up a good point about serverless. #490 (reply in thread)

[lilnasy]

I would like to see some activity on this RFC again.

My initial idea for the API looked very similar to matthewp's example. However, the frontmatter and how it handles state is already confusing to new users: some lines are metadata for the module, some are only executed during build, and others are executed once per request. Adding long living functions and their captured values into the mix will likely make it astro more unapproachable.

I still think the astro file is the easiest place to author server functions, so I'm eager to hear ideas, but in the meanwhile, here's a pattern I'm comfortable with.

Remotely callable functions are authored in and exported from src/serverfunctions

They can be imported by any server side or client side module

The server build imports the actual implementation

The client build transforms all imports into fetch calls

[torchsmith]

+1

[LopezNoah]

In your implementation, where would the fetch call be targeted against? Is there some query parameter that specifies the server function, or does it compile into a unique route?
I think query parameters would be a neat way to do this and that's what Remix does; however, Astro doesn't return early from its page routes since it streams the components. I think Next 13 is doing this with Server Actions but I'd have to double check. From my understanding, the functions get ids attached to them and those are passed through the POST request. That is how the server determines which functions to call and what parameters are coming in from the request.

[lilnasy]

@LopezNoah
The fetch target is /_sf, and the function is identified via a header called X-SF. Both of these are tentative implementation details and the user shouldn't have to worry about them.

I am hesitant around the idea of giving functions unique paths or query params. That's because I would like the same route to also host a WebSocket (and WebTransport in the future), given the adapter provides an implementation.

[LopezNoah]

That makes sense to use a header. I do think it'd be cool to allow this directly in the Astro pages, but just early return with the response from the server function when the X-SF header is present. Although, that is probably just me being comfortable with how Remix implements loaders and actions on the same page as the UI.

If you haven't had a chance to look at RocketRPC, you should definitely check it out. It uses Proxy objects so that you can write code on the client the same way you would write it on the server with type-safety too. It ends up invoking function calls on the server based on the request. There's limitations in it for sure such as authorization and potentially shooting yourself in the foot by exposing a function but I definitely recommend taking a look.

[lilnasy]

Revealing what ORM I'm using to someone trying to reverse engineer, for example, is something I want to avoid for my use cases, but wow, RocketRPC's approach is really impressive!

[kyjus25]

Personally I like OP's example regardless of if it works with serverless environments. Put up a disclaimer in the docs and call it macaroni imho. Surely there's ways long term to convert the functions in serverless mode to spin up new endpoint shenanigans instead of an RPC. This would be too huge of a win to not head this direction if you ask me.

[kyjus25]

P.S. - I'm also a little bias as this is a step toward #595 and server form actions.

[lilnasy]

Summary

Astro is uniquely positioned to offer a way to author client-callable server-side functions with fewer caveats than comparable solutions.

Background & Motivation

This RFC is inspired by the recent advent of framework-native RPC solutions in the JS ecosystem. Next.js users can leverage server components, and Nuxt has an active RFC. I think Astro could do something even better, with fewer of the downsides of server functions elsewhere.

Overview

Note: All naming is tentative.

Authoring server functions

Server functions can be authored in two places:

• in src/serverfunctions.ts, or for better management, any js/ts module inside src/serverfunctions/,
• in the frontmatter of an Astro component or page.

In src/serverfunctions

All function exported from src/serverfunctions.ts, or any of the modules inside the src/serverfunctions/ directory, should be treated as server functions.

// src/serverfunctions.ts
import db from "orm"

const todoTable = await db.get("todos")

export function saveTodo(token: string, user: UserId, todo: { date: number, body: string }) {
    const authorized = await checkToken(user, token)
    if (!authorized) return { type: "failure", reason: "invalid token" }
    const result = await todoTable.add(user, todo)
    if (result.ok) return { type: "success" }
    else throw new Error("saving to database failed")
}

Functions exported from here should be able to freely use any locally scoped or imported variables. However, the user should be mindful of the viability of closures when deploying on a serverless platform.

In the frontmatter

---
import db from "orm"

async function isUsernameAvailable(username: string) {
    const users = await db.get("users")
    const preexisting = await users.get(username)
    if (preexisting !== undefined) return false
    else return true
}
---
<script define:serverfunctions={{ isUsernameAvailable }}>
    
    const onSubmit = async input => {
        if (await isUsernameAvailable(input.value))
            await sendFullForm()
       
        else showTryAgainMessage()
    }
    
</script>

Server function within frontmatter should be subject to more constraints:

• They should not be able to use the variables declared within the frontmatter
• They should not be able to use the Astro global.

This will allow the server function to safely be "hoisted" outside of the per-request lifecycle of the frontmatter, and avoid edge cases arising from that.

Imported variables don't present any quandaries regarding their lifetime, and should be allowed.

Implementation

Server function should receive special treatment in the two ways:

• The server should host them under a special path.
• The client bundle should transform each use to make remote calls instead.

Usage

Vanilla Astro

---
import { sf } from '../serverfunctions'
const initialData = await sf()
---
<script>
    import { sf } from '../serverfunctions'
    
    document.querySelector('button').onclick = async _ => {
        document.querySelector('pre').textContent = await sf()
    }
</script>

<button>Call a server function</button>
<p>Received Data:</p>
<pre>{initialData}</pre>

Svelte

<script lang="ts">
    import { sf } from '../serverfunctions'
    let data = ''
    const updateData = async _ => {
        data = await sf()
    }
</script>

<button on:click={updateData}>Call a server function</button>
<p>Received Data:</p>
<pre>{data}</pre>

During the server-side render, the unaltered local implementation of sf will be used. On the client side, a button press will result in a call being made to the server.

Type-safe server functions

Built-in interfaces and type-checking functions should be provided to ensure arguments or return values don't fail to serialize during runtime.

import { type Serializable, type ServerFunction, defineServerFunction } from "astro"

export async function serverFunctionOne(...args: Serializable[]): Promise<Serializable> {
    ...
}

export async function serverFunctionTwo(a: A, b: B) {
    ...
}
serverFunctionTwo satisfies ServerFunction

export const serverFunctionThree = defineServerFunction(async x => { ... })

Error handling

While computing the result of a server function, an error thrown on the server should result in an error thrown on the client. However, no details should be exposed to the user. Instead, the thrown error on the client should include a unique identifier, that can be cross-referenced in the server logs manually.

Goals

• Simplicity: The user should not have to pass types from server modules to client modules, or configure ports or paths.
• Security:
  • The body of the server function should NOT be in the client bundle.
  • Function names should be hashed, and configurable with a salt.
  • Uncaught exceptions should not be sent to the client.

Non-goals

• Compression: This would be a redundant effort. JS runtimes often have built-in automatic brotli and gzip content-encoding for HTTP, and per-message deflate for WebSockets.
• Stateful functions: Each function call should encode all its needed information as arguments. Per-connection state is out of scope.
• Rate-limiting/middleware: The implementation would not necessarily use HTTP as the request-response protocol. While server functions over fetch would work with the recently-introduced middleware, allowing it would create challenges introducing server functions over WebSockets.

[whizzzkid]

This looks great, was any progress made on this?

[lilnasy]

Yes

[ematipico]

Closing as we have Astro actions now