Crumbs

The Crumbs API provides client-side storage similar to browser cookies. Crumbs are stored locally and can have optional expiration times. They are domain-specific, meaning each GURT domain has its own isolated storage.

Storage location: %APPDATA%/Flumi/crumbs/[domain].json

API Reference

gurt.crumbs.set(options)

Sets a crumb with the specified name and value.

Parameters:

• options (table) - Configuration object with the following fields:
  • name (string, required) - The crumb name/key
  • value (string, required) - The crumb value
  • lifetime (number, optional) - Lifetime in seconds. If omitted, the crumb persists indefinitely

-- Set a permanent crumb
gurt.crumbs.set({
    name = "username",
    value = "gurted_user"
})

-- Set a temporary crumb (expires in 10 seconds)
gurt.crumbs.set({
    name = "session_token", 
    value = "abc123def456",
    lifetime = 10
})

-- Set a short-lived crumb (expires in 30 seconds)
gurt.crumbs.set({
    name = "temp_data",
    value = "temporary_value",
    lifetime = 30
})

gurt.crumbs.get(name)

Retrieves a crumb value by name. Returns nil if the crumb doesn't exist or has expired.

Parameters:

• name (string) - The crumb name to retrieve

Returns:

• string - The crumb value, or nil if not found/expired

-- Get a crumb value
local username = gurt.crumbs.get("username")
if username then
    trace.log("Welcome back, " .. username .. "!")
else
    trace.log("No username found")
end

gurt.crumbs.delete(name)

Deletes a crumb by name.

Parameters:

• name (string) - The crumb name to delete

Returns:

• boolean - true if the crumb existed and was deleted, false if it didn't exist

local wasDeleted = gurt.crumbs.delete("session_token")
if wasDeleted then
    trace.log("Session token removed")
else
    trace.log("Session token was not found")
end

gurt.crumbs.delete("temp_data")

gurt.crumbs.getAll()

Retrieves all non-expired crumbs for the current domain.

Returns:

• table - A table where keys are crumb names and values are crumb objects

Each crumb object contains:

• name (string) - The crumb name
• value (string) - The crumb value
• expiry (number, optional) - Unix timestamp when the crumb expires (only present for temporary crumbs)

local allCrumbs = gurt.crumbs.getAll()

for name, crumb in pairs(allCrumbs) do
    trace.log("Crumb: " .. name .. " = " .. crumb.value)
    
    if crumb.expiry then
        local remaining = crumb.expiry - (Time.now() / 1000)
        trace.log("  Expires in " .. math.floor(remaining) .. " seconds")
    else
        trace.log("  Permanent crumb")
    end
end

File Storage Format

Crumbs are stored in JSON files:

{
  "username": {
    "name": "username",
    "value": "alice",
    "created_at": 1672531200.0,
    "lifespan": -1.0
  },
  "session_token": {
    "name": "session_token", 
    "value": "abc123",
    "created_at": 1672531200.0,
    "lifespan": 3600.0
  }
}