API Reference

Application Management

local app = tui.newApp()

App Methods

• app:SetRoot(primitive, fullscreen) - Set the root component
• app:Run() - Start the application event loop
• app:Stop() - Stop the application
• app:SetFocus(primitive) - Set focus to a specific component
• app:Draw() - Queue a redraw
• app:SetInputCapture(function) - Set global key handler

UI Components

TextView

Display text content with advanced formatting, styling, and scrolling capabilities.

local textView = tui.newTextView(text)

Content & Behavior:

• textView:SetText(text) - Set display text
• textView:GetText() - Get current text
• textView:SetWrap(bool) - Enable/disable text wrapping
• textView:SetWordWrap(bool) - Enable/disable word wrapping
• textView:SetScrollable(bool) - Make content scrollable
• textView:SetRegions(bool) - Enable clickable regions

Enhanced Styling:

• textView:SetDynamicColors(bool) - Enable color markup parsing
• textView:SetBorder(bool) - Add border around component
• textView:SetBorderColor(color) - Set border color
• textView:SetBackgroundColor(color) - Set background color
• textView:SetTitle(title) - Set component title
• textView:SetTextColor(color) - Set text color

InputField

Text input component for user data entry with enhanced styling options.

local inputField = tui.newInputField()

Content & Behavior:

• inputField:SetLabel(label) - Set field label
• inputField:SetPlaceholder(text) - Set placeholder text
• inputField:GetText() - Get current input text
• inputField:SetText(text) - Set input text
• inputField:SetDoneFunc(callback) - Set completion callback

Enhanced Styling:

• inputField:SetBorder(bool) - Add border around input field
• inputField:SetBorderColor(color) - Set border color
• inputField:SetFieldBackgroundColor(color) - Set input background
• inputField:SetFieldTextColor(color) - Set input text color
• inputField:SetTitle(title) - Set component title

Button

Clickable button component for user actions with professional styling.

local button = tui.newButton(label)

Content & Behavior:

• button:SetLabel(label) - Set button label
• button:SetSelectedFunc(callback) - Set click handler

Enhanced Styling:

• button:SetBorder(bool) - Add border around button
• button:SetBorderColor(color) - Set border color
• button:SetBackgroundColor(color) - Set button background
• button:SetLabelColor(color) - Set button text color
• button:SetTitle(title) - Set component title

Flex

Flexible layout container for organizing components with styling support.

local flex = tui.newFlex()

Layout & Behavior:

• flex:SetDirection(direction) - Set layout direction (0=vertical, 1=horizontal)
• flex:AddItem(primitive, fixedSize, proportion, focus) - Add component to layout

Enhanced Styling:

• flex:SetBorder(bool) - Add border around container
• flex:SetBorderColor(color) - Set border color
• flex:SetBackgroundColor(color) - Set container background
• flex:SetTitle(title) - Set container title

Color Styling & Theming

Enhanced TUI components support professional color schemes and markup.

Color Constants (256-color palette)

-- Common color constants for consistent theming
local COLORS = {
    PRIMARY = 39,      -- Bright blue
    SUCCESS = 46,      -- Bright green  
    WARNING = 226,     -- Bright yellow
    DANGER = 196,      -- Bright red
    SECONDARY = 245,   -- Light gray
    DARK = 235,        -- Dark gray
    DARKER = 232,      -- Very dark gray
    LIGHT = 255,       -- White
    ACCENT = 201,      -- Bright magenta
    INFO = 51          -- Bright cyan
}

Dynamic Color Markup

Use color markup in text content when SetDynamicColors(true) is enabled:

-- Color markup format: [color_code]text[reset_color]
textView:SetDynamicColors(true)
textView:SetText("[46]SUCCESS:[255] Operation completed!")

-- Advanced example with multiple colors
local statusText = string.format([[
[%d]🎉 Welcome to Dashboard![%d]

[%d]Status:[%d] %s
[%d]Uptime:[%d] %s
]], 
    COLORS.PRIMARY, COLORS.LIGHT,
    COLORS.INFO, COLORS.LIGHT, "Online",
    COLORS.SUCCESS, COLORS.LIGHT, "2 days"
)

Professional Styling Example

-- Create a professionally styled component
local panel = tui.newTextView("")
panel:SetDynamicColors(true)
panel:SetBorder(true)
panel:SetTitle("📊 System Metrics")
panel:SetBorderColor(COLORS.INFO)
panel:SetBackgroundColor(COLORS.DARK)
panel:SetScrollable(true)

-- Button with custom styling
local button = tui.newButton("🚀 Execute")
button:SetBorder(true)
button:SetBorderColor(COLORS.SUCCESS)
button:SetBackgroundColor(COLORS.SUCCESS)
button:SetLabelColor(COLORS.LIGHT)

Event Handling

Event objects in input capture callbacks provide:

• event:Key() - Get key code
• event:Rune() - Get character rune

local app = tui.newApp()
local textView = tui.newTextView("[39]Hello from Hype![255]")
textView:SetDynamicColors(true)
textView:SetBorder(true)
textView:SetTitle("🚀 My Enhanced App")
textView:SetBorderColor(39) -- Blue border
textView:SetBackgroundColor(235) -- Dark background

app:SetInputCapture(function(event)
    if event:Key() == 27 then -- ESC key
        app:Stop()
        return nil
    end
    return event
end)

app:SetRoot(textView, true)
app:Run()

HTTP Client

local http = require('http')

GET Requests

local response, err = http.get(url, options)

Parameters:

• url - Target URL string
• options - Optional table with:
  • timeout - Request timeout in seconds
  • headers - Custom headers table

Response Structure:

{
  status = 200,
  body = "response body",
  headers = { ["Content-Type"] = "application/json" }
}

local http = require('http')
local response, err = http.get("https://api.example.com/data", {
    timeout = 10,
    headers = {["User-Agent"] = "MyApp/1.0"}
})

if response then
    print("Status:", response.status)
    print("Body:", response.body)
else
    print("Error:", err)
end

HTTP Server

local server = http.newServer()

Server Methods

• server:handle(pattern, handler) - Register route handler
• server:listen(port) - Start server on port
• server:stop() - Stop server

Handler Function

Handler functions receive request and response objects:

server:handle("/api/users", function(req, res)
    -- Request object (req) contains:
    -- req.method, req.url, req.path, req.headers, req.query, req.body
    
    -- Response object (res) methods:
    res:write(content)           -- Write text response
    res:json(table)              -- Write JSON response
    res:status(code)             -- Set HTTP status code
    res:header(key, value)       -- Set response header
end)

local http = require('http')
local server = http.newServer()

server:handle("/", function(req, res)
    res:json({ message = "Hello World!" })
end)

server:handle("/api/echo", function(req, res)
    res:json({ 
        method = req.method,
        path = req.path,
        query = req.query,
        body = req.body
    })
end)

server:listen(8080)
print("Server running on :8080")

Database Connection

local kv = require('kv')
local db, err = kv.open(path, options)

Parameters:

• path - Database file path
• options - Optional configuration table

Bucket Management

• db:open_db(bucketName) - Create/open bucket

Buckets are like tables in traditional databases, used to organize key-value pairs.

Basic Operations

• db:put(bucket, key, value) - Store key-value pair
• db:get(bucket, key) - Retrieve value by key
• db:delete(bucket, key) - Delete key
• db:close() - Close database connection

local kv = require('kv')
local db, err = kv.open("./data.db")

if not db then
    print("Error opening database:", err)
    return
end

-- Create/open bucket
db:open_db("users")

-- Store data
db:put("users", "john", "John Doe")
db:put("users", "jane", "Jane Smith")

-- Retrieve data
local name = db:get("users", "john")
print("User:", name)  -- Output: User: John Doe

-- Delete data
db:delete("users", "john")

-- Close database
db:close()

Batch Operations

• db:keys(bucket, prefix) - Get all keys (optionally with prefix)
• db:foreach(bucket, callback) - Iterate over all key-value pairs

-- Get all keys
local keys = db:keys("users")
for i, key in ipairs(keys) do
    print("Key:", key)
end

-- Get keys with prefix
local userKeys = db:keys("users", "user_")

-- Iterate over all key-value pairs
db:foreach("users", function(key, value)
    print(key .. " = " .. value)
    return true  -- Continue iteration
end)

Transaction Support

Transactions provide ACID guarantees for multiple operations.

local txn, err = db:begin_txn(readonly)

Transaction Methods

• txn:put(bucket, key, value) - Store in transaction
• txn:get(bucket, key) - Retrieve in transaction
• txn:delete(bucket, key) - Delete in transaction
• txn:commit() - Commit transaction
• txn:abort() - Abort transaction

-- Begin read-write transaction
local txn, err = db:begin_txn(false)
if not txn then
    print("Error starting transaction:", err)
    return
end

-- Perform multiple operations
txn:put("users", "alice", "Alice Johnson")
txn:put("users", "bob", "Bob Wilson")

-- Get data within transaction
local alice = txn:get("users", "alice")
print("Alice:", alice)

-- Commit all changes
local success, err = txn:commit()
if not success then
    print("Transaction failed:", err)
    txn:abort()
end

Getting Started

local crypto = require('crypto')

The crypto module provides modern cryptographic operations using the industry-standard JWK format for key management.

Key Generation

local jwk = crypto.generate_jwk(algorithm)

Supported Algorithms:

• "RS256", "RS384", "RS512" - RSA with SHA-256/384/512
• "ES256", "ES384", "ES512" - ECDSA with SHA-256/384/512
• "EdDSA" - Ed25519 (EdDSA)

Returns: JWK table with algorithm-specific fields

-- Generate RSA key
local rsa_key = crypto.generate_jwk("RS256")
print("RSA Key Type:", rsa_key.kty)  -- "RSA"

-- Generate ECDSA key  
local ecdsa_key = crypto.generate_jwk("ES256")
print("ECDSA Key Type:", ecdsa_key.kty)  -- "EC"

-- Generate Ed25519 key
local ed25519_key = crypto.generate_jwk("EdDSA")
print("Ed25519 Key Type:", ed25519_key.kty)  -- "OKP"

Digital Signatures

Signing

local signature = crypto.sign(jwk, message)

Parameters:

• jwk - Private JWK key (from generate_jwk)
• message - String data to sign

Returns: Binary signature string or nil on error

Verification

local is_valid = crypto.verify(public_jwk, message, signature)

Parameters:

• public_jwk - Public JWK key (from jwk_to_public)
• message - Original string data
• signature - Binary signature to verify

Returns: Boolean validation result

local crypto = require('crypto')

-- Generate key pair
local private_key = crypto.generate_jwk("ES256")
local public_key = crypto.jwk_to_public(private_key)

-- Sign message
local message = "Important document content"
local signature = crypto.sign(private_key, message)

if signature then
    print("✅ Message signed successfully")
    
    -- Verify signature
    local is_valid = crypto.verify(public_key, message, signature)
    
    if is_valid then
        print("✅ Signature verified!")
    else
        print("❌ Invalid signature")
    end
else
    print("❌ Signing failed")
end

Key Management

Extract Public Key

local public_jwk = crypto.jwk_to_public(private_jwk)

Extracts the public key component from a private JWK for sharing and verification.

Key Thumbprint

local thumbprint = crypto.jwk_thumbprint(jwk)

Generates a unique SHA-256 thumbprint for key identification (RFC 7638).

JSON Serialization

-- Export to JSON
local json_string = crypto.jwk_to_json(jwk)

-- Import from JSON
local jwk = crypto.jwk_from_json(json_string)

Convert JWK objects to/from JSON for storage and transmission.

local crypto = require('crypto')

-- Generate and manage keys
local private_key = crypto.generate_jwk("RS256")
local public_key = crypto.jwk_to_public(private_key)

-- Get unique identifier
local key_id = crypto.jwk_thumbprint(private_key)
print("Key ID:", key_id)

-- Serialize for storage
local private_json = crypto.jwk_to_json(private_key)
local public_json = crypto.jwk_to_json(public_key)

-- Save public key for sharing
local file = io.open("public_key.json", "w")
file:write(public_json)
file:close()

-- Later: load and use
local loaded_json = io.open("public_key.json"):read("*all")
local loaded_key = crypto.jwk_from_json(loaded_json)
print("Loaded key algorithm:", loaded_key.alg)

Security Best Practices

• Key Storage: Store private keys securely, never in plain text
• Algorithm Choice: Use ES256 for most applications (fast + secure)
• Key Rotation: Regularly rotate keys and use thumbprints for identification
• Public Key Sharing: Only share public keys, never private keys
• Message Integrity: Always verify signatures before trusting data

Algorithm Comparison

Performance Characteristics:
┌─────────┬─────────────┬─────────────┬──────────────┐
│ Algorithm│ Key Size    │ Signature   │ Performance  │
├─────────┼─────────────┼─────────────┼──────────────┤
│ RS256   │ 2048 bits   │ 256 bytes   │ Slower       │
│ ES256   │ 256 bits    │ 64 bytes    │ Fast         │
│ EdDSA   │ 256 bits    │ 64 bytes    │ Fastest      │
└─────────┴─────────────┴─────────────┴──────────────┘

Recommendations:

• ES256: Best general-purpose choice (NIST P-256)
• EdDSA: Fastest performance, modern alternative
• RS256: Use when RSA compatibility is required

Getting Started

local crypto = require('crypto')
local httpsig = require('httpsig')

HTTP Signatures provide message-level security by cryptographically signing HTTP requests and responses using the draft-cavage-http-signatures specification.

HTTP Request Signing

local signed_result = httpsig.sign(message, options)

Message Structure (Request):

{
    type = "request",
    method = "POST",           -- HTTP method
    path = "/api/users",       -- URL path
    headers = {                -- HTTP headers
        ["Host"] = "api.example.com",
        ["Content-Type"] = "application/json"
    },
    body = '{"name": "Alice"}'  -- Message body
}

Signing Options:

{
    jwk = private_key,                    -- Private JWK for signing
    key_id = "my-key-2024",              -- Key identifier
    headers = {"(request-target)", "host", "date", "digest"},  -- Headers to sign
    created = os.time(),                 -- Optional: signature creation time
    expires = os.time() + 300           -- Optional: signature expiration
}

Returns: Table with signed headers or nil on error

local crypto = require('crypto')
local httpsig = require('httpsig')

-- Generate signing key
local signing_key = crypto.generate_jwk("ES256")

-- Create request to sign
local request = {
    type = "request",
    method = "POST",
    path = "/api/transfer", 
    headers = {
        ["Host"] = "bank-api.com",
        ["Content-Type"] = "application/json"
    },
    body = '{"amount": 1000, "to": "account123"}'
}

-- Sign the request
local signed = httpsig.sign(request, {
    jwk = signing_key,
    key_id = "client-2024",
    headers = {"(request-target)", "host", "content-type", "digest", "date"}
})

if signed then
    print("✅ Request signed successfully")
    print("Signature:", signed.headers.signature:sub(1, 50) .. "...")
    print("Digest:", signed.headers.digest)
    print("Date:", signed.headers.date)
else
    print("❌ Signing failed")
end

HTTP Response Signing

Message Structure (Response):

{
    type = "response",
    status = 200,              -- HTTP status code
    headers = {                -- HTTP headers
        ["Content-Type"] = "application/json",
        ["Server"] = "MyAPI/1.0"
    },
    body = '{"status": "success"}'  -- Response body
}

-- Server response signing
local server_key = crypto.generate_jwk("RS256")

local response = {
    type = "response",
    status = 201,
    headers = {
        ["Content-Type"] = "application/json",
        ["Location"] = "/api/users/123"
    },
    body = '{"id": 123, "created": true}'
}

local signed_response = httpsig.sign(response, {
    jwk = server_key,
    key_id = "server-rsa-key",
    headers = {"(status)", "content-type", "location", "digest", "date"}
})

if signed_response then
    print("✅ Response signed by server")
    print("Status signed:", response.status)
end

Signature Verification

local result = httpsig.verify(message, options)

Verification Options:

{
    jwk = public_key,                    -- Public JWK for verification
    required_headers = {"host", "date"}, -- Headers that must be signed
    max_age = 300                       -- Max signature age in seconds
}

Returns: Verification result table

{
    valid = true,                       -- Boolean: signature valid
    key_id = "client-2024",            -- Key ID from signature
    algorithm = "ecdsa-256",           -- Algorithm used
    reason = "digest mismatch"         -- Error reason if invalid
}

-- Extract public key for verification
local public_key = crypto.jwk_to_public(signing_key)

-- Verify received message
local verification = httpsig.verify(received_message, {
    jwk = public_key,
    required_headers = {"host", "content-type"},
    max_age = 300  -- 5 minutes
})

if verification.valid then
    print("✅ Signature verified!")
    print("Signed by:", verification.key_id)
    print("Algorithm:", verification.algorithm)
    
    -- Process trusted message
    process_secure_request(received_message)
else
    print("❌ Invalid signature:", verification.reason)
    -- Reject untrusted message
    return_error("Signature verification failed")
end

Digest Operations

Message digests ensure content integrity and are automatically included when body content is present.

Create Digest

local digest = httpsig.create_digest(content, algorithm)

Parameters:

• content - String content to hash
• algorithm - "sha256" or "sha512" (default: "sha256")

Verify Digest

local is_valid = httpsig.verify_digest(content, digest_header)

local content = '{"sensitive": "data", "amount": 5000}'

-- Create digest
local digest = httpsig.create_digest(content, "sha256")
print("Digest:", digest)  -- "SHA-256=base64encodedHash"

-- Verify digest
local is_valid = httpsig.verify_digest(content, digest)
print("Valid:", is_valid)  -- true

-- Test with tampered content
local tampered = '{"sensitive": "HACKED", "amount": 5000}'
local tampered_valid = httpsig.verify_digest(tampered, digest)
print("Tampered valid:", tampered_valid)  -- false

Security Features

• Automatic Digest Creation: Body content automatically hashed and signed
• Tampering Detection: Modified content fails verification
• Replay Protection: Timestamps prevent replay attacks
• Flexible Headers: Sign any combination of HTTP headers
• Multiple Algorithms: Support for RSA, ECDSA, and Ed25519
• Key Identification: Key IDs enable multi-key scenarios

Common Use Cases

Webhook Security

-- Sign webhook payload
local webhook_signature = httpsig.sign({
    type = "request",
    method = "POST",
    path = "/webhook",
    headers = {
        ["Host"] = "client.example.com",
        ["X-Event-Type"] = "user.created"
    },
    body = '{"user_id": 123, "event": "created"}'
}, {
    jwk = webhook_signing_key,
    key_id = "webhook-2024"
})

API Authentication

-- Client signs API request
local api_request = httpsig.sign({
    type = "request", 
    method = "GET",
    path = "/api/user/profile",
    headers = {
        ["Host"] = "api.service.com",
        ["Authorization"] = "Bearer " .. access_token
    }
}, {
    jwk = client_key,
    key_id = "client-app-2024",
    headers = {"(request-target)", "host", "authorization", "date"}
})

Microservice Communication

-- Service-to-service authentication
local service_request = httpsig.sign({
    type = "request",
    method = "POST", 
    path = "/internal/process",
    headers = {
        ["Host"] = "worker-service",
        ["X-Service-ID"] = "gateway-v1"
    },
    body = process_data
}, {
    jwk = service_key,
    key_id = "gateway-service",
    created = os.time(),
    expires = os.time() + 60  -- 1 minute expiry
})

Best Practices

• Always Sign Critical Headers: Include host, date, and content-type
• Use Digest for Body Content: Include "digest" header when signing requests with bodies
• Set Reasonable Expiration: Use expires or max_age to prevent replay attacks
• Validate Required Headers: Specify required_headers in verification
• Key Management: Use unique key_id values and rotate keys regularly
• Algorithm Selection: Use ES256 for most applications (fast + secure)

Build Command

hype build script.lua [options]

Options

• -o, --output NAME - Set executable name
• --target PLATFORM - Target platform (current, linux, windows, darwin)

# Build for current platform
hype build myapp.lua

# Specify output name
hype build myapp.lua -o myserver

# Cross-compile for different platforms
hype build myapp.lua --target linux
hype build myapp.lua --target windows
hype build myapp.lua --target darwin

Run Command

Run Lua scripts directly for development and testing.

hype run script.lua [-- args...]

# Run script directly
hype run server.lua

# Pass command line arguments
hype run myapp.lua -- --port 3000 --debug

Command Line Arguments

Access arguments in your Lua scripts via the global arg table:

• arg[0] - Script/executable name
• arg[1], arg[2], ... - Command line arguments

-- args.lua
print("Script name:", arg[0])
print("Number of arguments:", #arg)

for i = 1, #arg do
    print("Arg " .. i .. ":", arg[i])
end

-- Usage: hype run args.lua -- hello world 123
-- Output:
-- Script name: args.lua
-- Number of arguments: 3
-- Arg 1: hello
-- Arg 2: world
-- Arg 3: 123