Implement file upload with Functions

Build a Hono endpoint that checks an uploaded file and writes it to an Object Storage bucket from a function.

Last updated

View as Markdown Agent setup

In this tutorial, you will build an upload endpoint that stores each file it receives in an Object Storage bucket. You will create a Hono project, write the upload handler, create a bucket with write access, deploy the project, and post a file to it.

The complete source of this example is in the file-upload package of the functions examples repository.

Prerequisites

1. Create the project

Azion CLI creates a project from a framework preset. For the full Hono walkthrough, refer to How to build with Hono.

To create the project:

Authenticate Azion CLI

Run the login command:

azion login

With no credential flags, the CLI opens a browser-based flow. It stores the credentials locally, and every later command is authorized against your account.

Initialize the project

Run Azion CLI in the directory that holds your projects:

azion init
Name the project

Enter a name, or press enter to accept the suggestion:

? Your applications name: (black-thor)
Select the Hono preset

Azion CLI lists one preset per framework:

Shell
01? Choose a preset: [Use arrows to move, type to filter]
02 Angular
03 Astro
04 Docusaurus
05 Eleventy
06 Emscripten
07 Gatsby
08 Hexo
09> Hono
10 Hugo
11 Javascript
12 ...
Select one of the available templates
Answer N to the local development server prompt

The remaining stages deploy the project instead of running it locally:

Do you want to start a local development server? (y/N)
Go to the project folder

Azion CLI names the folder after the project:

cd <your-project-name>

The folder holds the source code of the Hono application that the template supplies.

2. Write the upload handler

The handler answers a POST request on /upload. It parses the multipart form, checks the file, and writes it to a bucket. The write goes through the createObject method of the Azion Storage library.

The entry field of azion.config.js names the entry file of the project. Open that file and replace its contents with this code:

TypeScript
01import type { AzionBucketObject, AzionStorageResponse } from "azion/storage";
02import { createObject } from "azion/storage";
03import { Hono } from "hono";
04
05const app = new Hono();
06
07app.post("/upload", async (c) => {
08 const body = await c.req.parseBody();
09 const file = body["file"];
10
11 if (
12 !file ||
13 typeof file !== "object" ||
14 typeof file.arrayBuffer !== "function"
15 ) {
16 return c.json({ message: "Invalid file" }, 400);
17 }
18
19 const maxSize = 2 * 1024 * 1024; // 2 MB, in bytes.
20 if (file.size > maxSize) {
21 return c.json({ message: "File size exceeds 2MB limit" }, 413);
22 }
23
24 try {
25 const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> =
26 await createObject({
27 bucket: Azion.env.get("BUCKET_NAME")!,
28 key: file.name,
29 // @ts-expect-error content is wrongly typed
30 content: await file.arrayBuffer(),
31 });
32
33 if (error) {
34 throw new Error(error.message);
35 }
36
37 if (newObject) {
38 console.log(`Object created with key: ${newObject.key}`);
39 } else {
40 console.error("Failed to create object", error);
41 }
42
43 // @ts-expect-error content is wrongly typed
44 const content = new Uint8Array(newObject.content);
45
46 return c.body(content, {
47 status: 200,
48 headers: {
49 "Content-Type": file.type,
50 "Content-Disposition": `attachment; filename="${newObject?.key}"`,
51 "Content-Length": newObject?.size?.toString() ?? "0",
52 },
53 });
54 } catch (error) {
55 console.error("Error uploading file:", error);
56 return c.json({ message: "Error uploading file" }, 500);
57 }
58});
59
60export default app;

export default app is the ES Modules handler pattern, which Azion recommends over the Service Worker pattern. Four decisions sit in the code:

  • A file field that holds no file returns 400 with the body {"message":"Invalid file"}.
  • A file above the maxSize constant of 2 MB returns 413 with the body {"message":"File size exceeds 2MB limit"}.
  • createObject writes the file to the bucket named by the BUCKET_NAME environment variable. The object key is the name of the file.
  • A failure inside createObject returns 500 with the body {"message":"Error uploading file"}, and the exception reaches the function logs.

3. Configure storage permissions

The access level of a bucket decides what Azion Runtime does with it. A function writes objects only to a bucket whose access is read_write. A bucket set to read_only answers reads and rejects writes, and Azion Runtime reaches no content in a bucket set to restricted.

A bucket name is unique across all Azion accounts. It takes 6 to 63 characters, accepts letters, numbers, and the hyphen (-), and never starts with azion.

The handler reads the bucket name from the BUCKET_NAME environment variable. To create the bucket and store its name:

Create the bucket the handler writes to
azion create storage bucket --name "<your-bucket-name>" --workloads-access 'read_write'

The bucket exists on your account, and Azion Runtime writes objects to it.

Store the bucket name on your account

Enter the same name you gave the bucket:

azion create variables --key "BUCKET_NAME" --value "<your-bucket-name>" --secret false

The variable is stored on the account, and the function reads it with Azion.env.get('BUCKET_NAME'). A variable whose key contains password, pwd, secret, key, hash, encrypted, passcode, auth, or token is sent as a secret by default. The key BUCKET_NAME carries none of those substrings. The --secret flag defaults to true, so --secret false stores the bucket name as a plain value. A new value reaches a function only after the function is deployed again.

4. Deploy the project

To send the project to Azion:

Confirm which account Azion CLI uses

Print the authenticated account:

azion whoami

The terminal prints the email address of the account the commands run against.

Deploy the project

In the project folder, run:

azion deploy

The deploy uploads the function code and configures the application. It also creates the routing rules, applies the storage permissions, and returns a domain. The domain has the format https://xxxxxxx.map.azionedge.net. Propagation takes a few minutes, so wait before you request the endpoint.

Azion CLI opens the browser on the page of Azion Console that carries the deployment logs. When the browser does not open, use the link the terminal prints.

5. Verify the upload

To store a file through the endpoint:

Create a text file

Write one line into a local file:

echo "Azion file upload test" > upload-test.txt

The file upload-test.txt exists in the current directory.

Post the file to the upload route

Send the file in a multipart form, under the file field:

curl -F "file=@upload-test.txt" https://<your-azion-domain>/upload

The response body carries the stored object:

Azion file upload test
List the objects of the bucket

Read the keys the bucket holds:

azion list storage object --bucket-name "<your-bucket-name>"

The key upload-test.txt appears in the list.

The endpoint now stores every file it accepts. A request whose file field holds no file answers 400, and a file above 2 MB answers 413. When a request answers 500, read the function logs for the exception behind it.

Next steps

Object StorageBucket permissions, object keys, prefixes, and the operation classes that are billed.Azion Storage libraryEvery method of azion/storage, including getObjectByKey, updateObject, and deleteObject.Environment variablesStore configuration and secrets outside the function code, then read each one by key at run time.Troubleshoot function execution and logsThe fixes for a function that never runs, stops before it responds, or writes nothing to the logs.Functions best practicesWhat each part of the handler does, and the design choices that keep an invocation inside its limits.LimitsThe body size a function processes per plan, and every other Functions ceiling.