docs(srv): update handler reference MTA-5521 (#4342)

* docs(srv): update * docs(srv): update * docs(srv): update * docs(srv): update * docs(srv): update * docs(srv): update
scaleway · Feb 5, 2025 · f0cb3e0 · f0cb3e0
1 parent 5c4b196
commit f0cb3e0
Show file tree

Hide file tree

Showing 3 changed files with 127 additions and 21 deletions.
diff --git a/menu/navigation.json b/menu/navigation.json
@@ -3719,7 +3719,7 @@
                     "slug": "test-a-function"
                   },
                   {
-                    "label": "Package function dependencies in a zip file",
+                    "label": "Package function in a zip file",
                     "slug": "package-function-dependencies-in-zip"
                   },
                   {

diff --git a/pages/serverless-functions/how-to/package-function-dependencies-in-zip.mdx b/pages/serverless-functions/how-to/package-function-dependencies-in-zip.mdx
@@ -1,13 +1,13 @@
 ---
 meta:
-  title: How to package your function and dependencies to a zip file and upload it
+  title: How to package your function to a zip file and upload it
   description: Package function dependencies in a ZIP file for Scaleway Serverless Functions.
 content:
-  h1: How to package your function and dependencies to a zip file and upload it
+  h1: How to package your function to a zip file and upload it
   paragraph: Package function dependencies in a ZIP file for Scaleway Serverless Functions.
-tags: functions zip-file 
+tags: functions zip-file handler package
 dates:
-  validation: 2024-10-23
+  validation: 2025-02-04
   posted: 2021-05-26
 categories:
   - serverless
@@ -30,6 +30,10 @@ There are [different methods to deploy functions](/serverless-functions/referenc
 
 To match the Scaleway build pipelines requirements, functions zip files must contain the content of the root folder you want to publish.
 
+<Message type="important">
+Avoid compressing your function using the file explorer or finder, as this method can create an additional folder in the file structure of your function, which can lead to build errors. Refer to the [troubleshooting](#troubleshooting) section for more information.
+</Message>
+
 ### How to create a zip file 
 
 Use the `zip` command to create an archive of your function and its dependencies:
@@ -369,3 +373,19 @@ Like that, you can create 3 functions with the same zip file simply by changing
 
 You can also create a single Serverless Function with several handlers in the same zip file, and change the [handler](/serverless-functions/concepts/#handler) parameter according to your needs.
 
+## Troubleshooting
+
+If you encounter build errors after packaging your function, make sure that your archive is properly structured, as shown above. Compressing a folder from its parent directory will include this folder in the archive structure that can lead to build errors while deploying your function.
+
+To avoid archive structure issue, make sure to zip your function from its root folder, and not the parent directory by using the following method:
+
+```bash
+cd folder_i_want_to_zip
+zip -r ../function.zip .
+```
+
+You can then use the `unzip` command with the `-v` option to list the content of your archive to ensure it is properly structured:
+
+```bash
+unzip -v ../func.zip
+```
diff --git a/pages/serverless-functions/reference-content/functions-handlers.mdx b/pages/serverless-functions/reference-content/functions-handlers.mdx
@@ -14,6 +14,10 @@ categories:
   - functions
 ---
 
+A handler is a routine/function/method that processes specific events. Upon invoking your function, the handler is executed and returns an output.
+
+To learn how to package a function and its dependencies in a zip file, refer to the [dedicated documentation](/serverless-functions/how-to/package-function-dependencies-in-zip).
+
 ## Handler syntax
 
 <Tabs id="handlers">
@@ -27,6 +31,17 @@ categories:
 
     - If the `handle` function is defined in a file named `handler.py` within a folder (for example, `myFunction/handler.py`): the handler will be `myFunction/handler.handle`.
 
+    #### Python handler example
+
+    ```py
+    def handle(event, context):
+    return {
+        "body": {
+            "message": 'Hello, world',
+        },
+        "statusCode": 200,
+    }
+    ```
   </TabsTab>
 
   <TabsTab label="Node">
@@ -39,6 +54,18 @@ categories:
 
     - If the `handle` function is defined in a file named `handler.js` within a folder (for example, `myFunction/handler.js`): the handler will be `myFunction/handler.handle`.
 
+    #### Node handler example
+
+    ```js
+    export {handle};
+
+    function handle (event, context, cb) {
+        return {
+            body: process.version,
+            statusCode: 200,
+        };
+    };
+    ```
   </TabsTab>
 
   <TabsTab label="PHP">
@@ -51,33 +78,92 @@ categories:
 
     - If the `handle` function is defined in a file named `handler.php` within a folder (for example, `myFunction/handler.php`): the handler will be `myFunction/handler.handle`.
 
+    #### PHP handler example
+
+    ```php
+    <?php
+    function handle($event, $context) {
+      return [
+        "body" => phpversion(),
+        "statusCode" => 200,
+      ];
+    }
+    ```
   </TabsTab>
 
   <TabsTab label="Go">
 
-      For Go, the handler must be written in the `<folder>/<function_name>` format:
-
-      - If the `Handle` function is defined in a `handler.go` file in a root folder: the handler name will be `Handle`.
-
-      - If the `Handle` function is defined in a `handler.go` file (for example, `myFunction/handler.go`): the handler will be `myFunction/Handle`
-
-      <Message type="note">
-      With Go, the method name must be capitalized.
-      </Message>
-
+    For Go, the handler must be written in the `<folder>/<function_name>` format:
+
+    - If the `Handle` function is defined in a `handler.go` file in a root folder: the handler name will be `Handle`.
+
+    - If the `Handle` function is defined in a `handler.go` file (for example, `myFunction/handler.go`): the handler will be `myFunction/Handle`
+
+    <Message type="note">
+    With Go, the method name must be capitalized.
+    </Message>
+
+    #### Go handler example
+
+    ```go
+      package myfunc
+
+      import (
+          "encoding/json"
+          "net/http"
+      )
+
+      // Handle - Handle event
+      func Handle(w http.ResponseWriter, r *http.Request) {
+          response := map[string]interface{}{
+            "message": "We're all good",
+          }
+
+          responseBytes, err := json.Marshal(response)
+          if err != nil {
+            w.WriteHeader(http.StatusInternalServerError)
+            return
+          }
+
+          // Set the header explicitly depending the returned data
+          w.Header().Set("Content-Type", "application/json")
+
+          // Customise status code.
+          w.WriteHeader(http.StatusOK)
+
+          // Add content to the response
+          _, _ = w.Write(responseBytes)
+      }
+      ```
   </TabsTab>
 
   <TabsTab label="Rust">
 
-      For Rust, the handler must be written in the `<folder>/<function_name>` format:
+    For Rust, the handler must be written in the `<folder>/<function_name>` format:
+
+    - If the `handle` function is defined in a `handler.rs` file in a root folder: the handler name will be `handle`.
 
-      - If the `handle` function is defined in a `handler.rs` file in a root folder: the handler name will be `handle`.
+    - If the `handle` function is defined in a `handler.rs` file (for example, `myFunction/handler.rs`): the handler will be `myFunction/handle`
 
-      - If the `handle` function is defined in a `handler.rs` file (for example, `myFunction/handler.rs`): the handler will be `myFunction/handle`
+    <Message type="note">
+    With Rust, the method must be exported using the `pub` keyword.
+    </Message>
 
-      <Message type="note">
-      With Rust, the method must be exported using the `pub` keyword.
-      </Message>
+    #### Rust handler example
 
+    ```rust
+      use axum::{
+          body::Body, extract::Request, response::Response,
+      };
+      use http::StatusCode;
+
+      pub async fn handle(_req: Request<Body>) -> Response<Body> {
+          Response::builder()
+              .status(StatusCode::OK)
+              .header("Content-Type", "text/plain")
+              .body(Body::from("Hello world!"))
+              .unwrap()
+      }
+      ```
   </TabsTab>
 </Tabs>