File Upload Functions

Parse multipart form data and upload files to SolidB blob storage. Handle file uploads with metadata preservation and easy retrieval.

Looking for the model-level DSL?

For attachments tied to a model (avatars, document attachments, gallery photos), prefer the uploader(...) declaration. It owns validation, storage, and replace-on-update from a single line on the model and pairs with the uploads(resource, field) route helper for show/create/destroy endpoints.

The functions below are the low-level primitives the DSL builds on. Use them directly when you need fine-grained control or when the upload isn't model-bound.

set_solidb_address(addr)

Configures the global SoliDB address for upload functions. Call this once during app initialization.

Parameters

addr (String) - SoliDB server address (e.g., "http://localhost:8529")

Returns Null

Example

# Call once during app startup
set_solidb_address("http://localhost:8529")

parse_multipart(req)

Parses multipart/form-data from a request and extracts file information.

Parameters

req (Hash) - Request hash with body and headers

Returns Array of file hashes with keys: filename, content_type, size, data_base64, field_name

Example

let files = parse_multipart(req)
for file in files {
    println("Uploaded: " + file["filename"] + " (" + str(file["size"]) + " bytes)")
}

upload_to_solidb(req, collection, field_name)

Uploads a single file from multipart form data directly to SolidB blob storage. Uses the global SoliDB address set by set_solidb_address().

Parameters

req (Hash) - Request hash
collection (String) - SolidB collection name
field_name (String) - Form field name to upload

Returns Hash with blob_id, filename, size, content_type

let result = upload_to_solidb(req, "uploads", "avatar")
if has_key(result, "blob_id")
    println("Uploaded: " + result["filename"])
    println("Blob ID: " + result["blob_id"])
end

upload_all_to_solidb(req, collection)

Uploads all files from multipart form data to SolidB. Uses the global SoliDB address set by set_solidb_address().

Parameters

req (Hash) - Request hash
collection (String) - SolidB collection name

Returns Array of result hashes (one per file, or error hash if failed)

let results = upload_all_to_solidb(req, "uploads")
for result in results
    if has_key(result, "blob_id")
        println("Uploaded: " + result["filename"])
    else
        println("Failed: " + result["error"])
    end
end

get_blob_url(collection, blob_id, base_url?, expires_in?)

Generates a URL for downloading a blob from SolidB. If base_url is not provided, uses the global SoliDB address set by set_solidb_address().

Parameters

collection (String) - SolidB collection name
blob_id (String) - Blob ID returned from upload
base_url (String, optional) - Base URL for SolidB server. Uses global address if not provided.
expires_in (Int, optional) - Expiration time in seconds

Returns String - Download URL

Example

# Using global address
let url = get_blob_url("avatars", blob_id)

# With explicit base_url
let url = get_blob_url("avatars", blob_id, "http://localhost:8529")

SolidB Blob Methods

Methods available on Solidb instances for blob storage.

solidb.store_blob(collection, data_base64, filename, content_type)

Stores a file as a blob in SolidB.

collection (String) - Collection name
data_base64 (String) - File content as base64
filename (String) - Original filename
content_type (String) - MIME type

Returns: String - Unique blob ID

let db = Solidb("localhost:5678", "myapp")
let blob_id = db.store_blob("avatars", image_data_base64, "photo.jpg", "image/jpeg")

solidb.get_blob(collection, blob_id)

Retrieves a blob from SolidB.

Returns: String - File content as base64

let image_data = db.get_blob("avatars", blob_id)

solidb.get_blob_metadata(collection, blob_id)

Gets metadata for a blob without fetching the data.

Returns: Hash with _key, filename, content_type, size, created_at

solidb.delete_blob(collection, blob_id)

Deletes a blob from SolidB.

Returns: String - "OK" on success

Complete Example

Manual flow using the primitives on this page:

# App initialization (call once)
set_solidb_address("http://localhost:8529")

# Upload controller
def upload_avatar
    let collection = "avatars"

    let result = upload_to_solidb(req, collection, "avatar")

    if has_key(result, "error")
        return {
            "status": 400,
            "body": json_stringify({ "error": result["error"] })
        }
    end

    let blob_url = get_blob_url(collection, result["blob_id"])

    {
        "status": 201,
        "body": json_stringify({
            "message": "File uploaded successfully",
            "blob_id": result["blob_id"],
            "filename": result["filename"],
            "size": result["size"],
            "content_type": result["content_type"],
            "url": blob_url
        })
    }
end

# Get file controller
def get_file
    let blob_id = req["params"]["id"]
    let db = Solidb("localhost:8529", "myapp")

    let metadata = db.get_blob_metadata("avatars", blob_id)
    if metadata["_key"] == null
        return { "status": 404, "body": "Not found" }
    end

    let data = db.get_blob("avatars", blob_id)

    {
        "status": 200,
        "headers": {
            "Content-Type": metadata["content_type"],
            "Content-Length": str(metadata["size"]),
            "Content-Disposition": "attachment; filename=\"" + metadata["filename"] + "\""
        },
        "body": data
    }
end

Same flow with the model-level uploader DSL:

# app/models/user.sl
class User < Model
    uploader("avatar", {
        "multiple":      false,
        "content_types": ["image/jpeg", "image/png"],
        "max_size":      2_000_000
    })
end

# config/routes.sl
uploads("users", "avatar")  # auto-mounts GET/POST/DELETE /users/:id/avatar

# app/controllers/users_controller.sl — upload from a regular edit form
def update
    @user = User.find(params.id)
    if @user.update(this._permit(params))
        file = find_uploaded_file(req, "avatar")
        @user.attach_avatar(file) unless file.nil?
        return redirect("/users/#{@user._key}")
    end
    render("users/edit")
end

The DSL handles validation, base64 encoding, replace-on-upload, and orphan cleanup. Pair it with before_delete("cleanup_uploads") + detach_all_uploads(self) to remove blobs when the record is destroyed.