Appwrite Functions G4 #5016

Meldiron · 2023-01-18T12:58:16Z

Meldiron
Jan 18, 2023
Maintainer

`helloWorld()` 👋

🎓 Background

Appwrite Functions let you extend Appwrite's backend capabilities with your own backend code written in your favourite language. Functions can help you with scheduled task such as cleanup, event-triggered tasks such as invoice generation, or http-triggered tasks to implement your own Appwrite "endpoints".

Functions are currently fast and powerful, but there are some downsides and limitations. To address them, we plan to introduce new generation of functions 🔥 This discussion describes our suggested changes. Keep in mind it's a discussion and nothing is set in stone.

💎 Backwards Compatibility

All existing functions will be backwards compatible, and you won't need to re-write function to a new generation.

All new functions made after upgrading Appwrite will need to be written in a new syntax.

🤖 Syntax Changes

Hello world

Current Generation:

module.exports = async (req, res) => {
  res.json({
    msg: 'Hello 👋',
  });
};

New Generation:

module.exports = async (context) => {
  return context.res.json({
    msg: 'Hello 👋',
  });
};

On first look, almost everything stays the same. Request and response objects are now under context, and you have to return when sending response 😇

In some languages you can even use Destructuring assignment, to only extract needed parts of context:

module.exports = async ({ req, res }) => {
  return res.json({
    msg: 'Hello 👋',
  });
};

Working with payload

Current Generation:

module.exports = async (req, res) => {
  const name = JSON.parse(req.payload ?? '{}').name;
  res.send(`Your name is ${name}`);
};

New Generation:

module.exports = async (context) => {
  const name = context.req.body.name;
  return context.res.send(`Your name is ${name}`);
};

payload is now body so users from other backgrounds will understand the terminology automatically. Also notice that JSON bodies are automatically parsed for you 🎉

Variables

module.exports = async (req, res) => {
  const maxUsers = req.variables.MAX_USERS;
  res.send(`Your variable is ${maxUsers}`);
};

New Generation:

module.exports = async (context) => {
  const maxUsers = process.env.MAX_USERS;
  return context.res.send(`Your variable is ${maxUsers}`);
};

HTTP standard does not know variables. It was something introduced by Appwrite. We don't want developers to learn new concepts. We want to meet developers where they are, and so we removed variables form the request object. New generation will provide all variables as system environment variables. This is a common pattern seen in other frameworks, for instance Next.JS 🤝

Logging

module.exports = async (req, res) => {
  console.log('Function started');
  console.error('Whoops, something is wrong.');

  res.send('OK');
};

New Generation:

module.exports = async (context) => {
  context.log('Function started');
  context.error('Whoops, something is wrong.');

  return context.res.send('OK');
};

We introduced two logging functions under context instead of hooking into language native logging methods. This change allows more reliable per-execution logging that Appwrite community liked since it got introduced.

🔮 Future possibilities

New generation will introduce a custom URL for functions. For example, you could have URL my-function.my-project.appwrite.myapp.com. You can send request of any kind to this endpoint and your function will be triggered. This can be helpful when trying to use Appwrite without SDKs, or when using Appwrite function as webhook for payment gateway integration.

When using this function URLs, some more options become possible.

Request headers

module.exports = async (context) => {
  const stripeKey = context.request.headers['stripe-signature'];
  return context.res.send('Stripe webhook recieved');
};

More request information

module.exports = async (context) => {
  const { url, method, body } = context.req;
  return context.res.json({ url, method, body });
};

HTML response

const fs = require('fs');

// I am doing cool trick here, only reading file once during cold start. It's kept in memory for quick response to each execution
const indexFile = fs.readFileSync(__dirname + '/index.html').toString();

module.exports = async (context) => {
  return context.res.html(indexFile);
};

File response

module.exports = async (context) => {
  return context.res.file('kitty.png', 200, { 'content-type': 'image/png' });
};

Redirect

module.exports = async (context) => {
  // Pseudo-code
  const order = stripe.createNewOrder(products);
  const paymentUrl = order.publicUrl;
  
  // Real code
  return context.res.redirect(paymentUrl);
};

Let us know what you think! 🔥

We are satisfied with our implementation but we believe transparency is a key to success. We are opening this discussion to public and would love to hear what you love and what you hate about the new generation. Let's chat 😇

monzim · 2023-01-18T13:52:54Z

monzim
Jan 18, 2023

Are we going to see golang support for functions?

1 reply

stnguyen90 Jan 20, 2023
Maintainer

This is almost ready! The PR is just pending merge and a quick update in Appwrite!

stnguyen90 · 2023-01-26T01:02:34Z

stnguyen90
Jan 26, 2023
Maintainer

Also notice that JSON bodies are automatically parsed for you

@Meldiron, how does this work for Appwrite considering data is sent as a string? What if the developer doesn't want to pass a JSON string?

2 replies

tannermeade Aug 8, 2023

@Meldiron @stnguyen90 If Appwrite parses the JSON for you Stripe webhook is impossible to implement because the security validation requires the function to have access to the raw unparsed text of the request.

tannermeade Aug 8, 2023

Looks like they may have added an extra param so the function can have access to the raw body: https://github.com/open-runtimes/open-runtimes/blob/main/runtimes/node-16.0/src/server.js#L26

stnguyen90 · 2023-01-26T01:05:07Z

stnguyen90
Jan 26, 2023
Maintainer

New generation will provide all variables as system environment variables.

I think it might be worth mentioning some variables like APPWRITE_FUNCTION_JWT and APPWRITE_FUNCTION_USER_ID will end up being in the request headers.

0 replies

zlmr · 2023-02-24T20:18:46Z

zlmr
Feb 24, 2023

Would it be possible to add option to upload prebuilt binaries instead of code? So basically something that was possible in versions prior to 0.13.
That would reduce server resources by a lot since building takes a lot of CPU/RAM for some runtimes like Java/Kotlin.

Would also benefit you for Appwrite Cloud - I am using 4cores/8GB server and it is already struggling when I have to deploy 25 functions.

Not sure if the questio 8000 n is out of scope but since you are refactoring functions maybe it is worth giving it a look.

0 replies

rafagazani · 2023-02-25T14:52:45Z

rafagazani
Feb 25, 2023

@Meldiron Do you have a release date?

1 reply

tannermeade Aug 8, 2023

I don't work at Appwrite, but here is the progress in github:

Functions V4 requires changes to the runtime environments (openruntimes). I believe this is the PR for the runtimes that'll be used in functions v4: open-runtimes/open-runtimes#136 (merged)

I think this will be the main PR to get functions v4 done/merged into main: appwrite/docs#398

it's a draft PR right now, but looks like good progress.

lucasctd · 2023-03-19T01:53:19Z

lucasctd
Mar 19, 2023

payload is now body so users from other backgrounds will understand the terminology automatically. Also notice that JSON bodies are automatically parsed for you 🎉
Any plans to parse the response too?

That's what we have now:

{
    "$id": "64165dbc616d0cxxxx95c",
    "$createdAt": "2023-03-19T00:56:28.410+00:00",
    "$updatedAt": "2023-03-19T00:56:43.844+00:00",
    "$permissions": [],
    "functionId": "functionId",
    "trigger": "http",
    "status": "completed",
    "statusCode": 422,
    "response": "{\"message\":\"My message.\"}",
    "stdout": "",
    "stderr": "",
    "duration": 0.105232
}

I wish it could look like this:

{
    "$id": "64165dbc616d0cxxxx95c",
    "$createdAt": "2023-03-19T00:56:28.410+00:00",
    "$updatedAt": "2023-03-19T00:56:43.844+00:00",
    "$permissions": [],
    "functionId": "functionId",
    "trigger": "http",
    "status": "completed",
    "statusCode": 422,
    "response": {"message": "My Message"}
    "stdout": "",
    "stderr": "",
    "duration": 0.105232
}

0 replies

wilhantian · 2023-05-29T09:28:20Z

wilhantian
May 29, 2023

Hi, I think customizing URLs is an urgent feature. When will it be released?

0 replies

Whitehat645 · 2023-06-12T16:44:40Z

Whitehat645
Jun 12, 2023

when can we get this feature as this is a basic need, as we need to get web requests outside appwrite like payment gateways, what can we do without that guys, should we launch a ecom App for free.

0 replies

byawitz · 2023-06-12T17:08:27Z

byawitz
Jun 12, 2023
Collaborator

For anyone who needs to have URL access to your functions, you can try:

Function Proxy - https://github.com/stnguyen90/appwrite-function-proxy
Funcover - https://github.com/BoolCode/appwrite-funcover

Funcover Docker container will provide you with anything you need (including headers) to use your Appwrite function as an input webhook.

0 replies

moshOntong-IT · 2023-07-30T04:41:25Z

moshOntong-IT
Jul 30, 2023

is this new generation can support implementing discord bot?

3 replies

byawitz Jul 31, 2023
Collaborator

Do you mean it will be possible to develop a Discord bot using the future Appwrite functions version?

moshOntong-IT Aug 1, 2023

yes

byawitz Aug 1, 2023
Collaborator

Then yes, the next version should enable developing any incoming webhooks using functions.

Meldiron · 2023-09-07T12:19:46Z

Meldiron
Sep 7, 2023
Maintainer Author

Thanks everyone for your feedback, generation 4 of Appwrite Functions was released in Appwrite 1.4 🎉

0 replies

Appwrite Functions G4 #5016

Uh oh!

Meldiron Jan 18, 2023 Maintainer

helloWorld() 👋

🎓 Background

💎 Backwards Compatibility

🤖 Syntax Changes

Hello world

Working with payload

Variables

Logging

🔮 Future possibilities

Request headers

More request information

HTML response

File response

Redirect

Replies: 11 comments · 7 replies

Uh oh!

Uh oh!

Uh oh!

stnguyen90 Jan 20, 2023 Maintainer

Uh oh!

stnguyen90 Jan 26, 2023 Maintainer

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stnguyen90 Jan 26, 2023 Maintainer

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

byawitz Jun 12, 2023 Collaborator

Uh oh!

Uh oh!

byawitz Jul 31, 2023 Collaborator

Uh oh!

Uh oh!

byawitz Aug 1, 2023 Collaborator

Uh oh!

Meldiron Sep 7, 2023 Maintainer Author

Meldiron
Jan 18, 2023
Maintainer

`helloWorld()` 👋

Replies: 11 comments 7 replies

stnguyen90 Jan 20, 2023
Maintainer

stnguyen90
Jan 26, 2023
Maintainer

stnguyen90
Jan 26, 2023
Maintainer

byawitz
Jun 12, 2023
Collaborator

byawitz Jul 31, 2023
Collaborator

byawitz Aug 1, 2023
Collaborator

Meldiron
Sep 7, 2023
Maintainer Author