Local File Driver

Iridium bundles a local file driver to get you started with uploading files to your server.

Our driver is one interpretation of a server-side file system designed to work with filepond.

Forking

We encourage you to fork our driver and customize it to your needs if our interpretation does not fit your requirements. The source code is available on GitHub.

Create a new file in your project, copy our contents, and start customizing. It must adhere to our FileDriver interface to be registered with Iridium and adhere to the expectations of filepond.

Introduction

You can instantiate and pass a new LocalFileDriver to your FileUpload as so:

import "github.com/iridiumgo/iridium/core/files"

fileDriver := files.NewLocalFileUploader("/tmp", "/storage", false)
FormFileUpload("avatars", fileDriver)

Where the first argument is the root directory for temporary files, and the second argument is the root directory for permanent files, and the third argument is a boolean indicating whether to enable CORS.

TIP

Your FormFileUpload can take a path to change which directory it uploads to. The directories passed into the file driver are just the root directories.

For example, you may have your temporary and storage roots at /tmp and /storage, and use the PathFn method to change the directory based on another field in your form.

FormSelect("reports").
    OptionsUnordered(map[string]string{
        "daily": "Daily Report",
        "weekly": "Weekly Report",
    })

// A user first selects a report type, then uploads a file.
// The file will be uploaded to /storage/reports/daily or /storage/reports/weekly.
FormFileUpload("reports", files.NewLocalFileUploader("/tmp", "/storage", false).
    PathFn(func(ctx FieldContext) string {
        reportType, err := Get[string](ctx, "reports")
        if err != nil {
            return "default"
        }
        return fmt.Sprintf("/reports/%s", reportType)
    }))

Brief introduction to Filepond

We encourage you to read the official documentation to learn more about how to implement a server-side file system.

However, here is a brief summary of how our driver works:

1. A user selects a file to upload in the file uploader.
2. By default, the file will be automatically uploaded to the /tmp directory as soon as the user selects it.
3. The server will then return a unique identifier for the file back to the client.
4. When a user submits the form, they will send all the file unique identifiers back to the server. Those UUIDs are then used to retrieve the files from the /tmp directory, and move them to the /storage directory.

If a user uploads a file, then either doesn't submit the form, or leaves the page, etc. the file will remain in the /tmp directory forever. This is by design. You have to enable our prebuilt janitor to periodically clean up the /tmp directory. Or you can implement your own cleanup logic.

UUIDs and file names

Once uploaded, our driver will return a unique identifier for the file. It also appends the UUID to the name of the file in the /tmp directory. This is to avoid collisions and also as a security measure.

If a user requests to download a file, the UUID is stripped and the original file name is returned.

Janitor

We encourage you to write your own janitor to periodically clean up the /tmp directory. We have written a simple janitor that you can use as a reference or enable in your project. It runs every 30 minutes and clears files older than 24 hours.

fileDriver := files.NewLocalFileUploader("/tmp", "/storage", false)

// Start the janitor for the /tmp directory. 
// Run every 30 minutes and clear files older than 24 hours.
fileDriver.StartJanitor("/tmp", 30*time.Minute, 24*time.Hour)

Limitations

• Our driver currently does not support chunked uploads.