Trezo Funk

Trezo Funk is a serverless function execution framework built with Go, Chi, and PostgreSQL. It provides a foundational HTTP server using Chi for routing and pgx for high-performance PostgreSQL connectivity.

Disclaimer: This project is under active development. Until further notice, there will be no focus on providing releases, Docker images, etc.

What's up with the name?

Trezo Funk serves as the function execution backbone for TrezoFlow (treasure flow), a wealth management and portfolio tracking platform under development.

Overview

Function Execution Model

Trezo Funk implements a "poor man's" function runner designed for simplicity:

• Deployment: Developers upload pre-compiled binaries (Linux AMD64) along with necessary environment variables. Binaries must be self-contained (statically linked) with no dynamic library dependencies. Interpreted code is not supported; use languages such as Go, Bun, Dart, Rust, Zig, etc.
• Execution: When a function is triggered, the payload is written to a temporary file. The binary is then executed with the file path as its argument.

Security Implications

Important: This execution model implies significant trust. Only trusted parties should be allowed to upload binaries, as an uploaded binary can execute arbitrary code with the privileges of the runner process.

• Containerization: It is strongly recommended to run the Trezo Funk server within a container to limit the blast radius of executed functions.
• Sandboxing: Advanced sandboxing features are not currently implemented but may be considered for future releases.

Features

• HTTP Server: Chi v5 router with middleware (logging, recovery, request ID, real IP)
• Database: PostgreSQL connectivity via pgx v5 with connection pooling
• Configuration: Environment-based configuration with .env support
• Docker: Full Docker Compose setup for local development
• Hot Reload: Air integration for automatic rebuilds during development
• Health Check: /health endpoint for monitoring server and database status
• Long-Running Processes: Support for deploying background processes with automatic restart on failure

Prerequisites

Choose one of the following development setups:

• Docker setup: Docker and Docker Compose
• Local setup: Go 1.25 and PostgreSQL

Task is optional but recommended for convenient development commands.

Quick Start

1. Clone the repository:

   git clone <repository-url>
   cd trezo-funk

2. Copy the example environment file:

   cp .env-example .env

3. Modify .env for your needs. Note: several values can be used as is. Be aware that some values may be specific to the internal Docker network.

4. Start the database and trezo-funk server (containerized)

    task up

See the Server Development Setup Guide for detailed instructions on setting up with or without Docker.

Server Development

For Server architecture and development, see Server Development Documentation which covers:

• Development setup
• Configuration
• Architecture overview
• Testing

Function Development

For function and process creators, see the Function Development Documentation which covers:

• Deploying and managing functions and processes
• Function implementation details (payload handling, function-to-function calls)
• Process implementation details (configuration, lifecycle, invoking functions)
• User authentication setup (JWT-based login and sign-up functions)

Getting Started

We provide a function bootstrapping template project that includes example functions and tooling (build, deploy, etc.) written in Go. While it targets Go, the template also contains general instructions to help you get started creating function binaries in any language using any tool. As mentioned above, interpreted code is not supported—this includes Java and other languages that depend on a VM.

Project Structure

trezo-funk/
├── cmd/
│   └── server/
│       └── main.go              # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go            # Configuration management
│   ├── database/
│   │   └── database.go          # Database connection handling
│   └── server/
│       └── server.go            # HTTP server setup and routing
├── docs/
│   ├── function-development/    # Documentation for function creators
│   ├── server-development/      # Documentation for server contributors
│   └── README.md                # Documentation index
├── .air.toml                    # Air hot reload configuration
├── .env-example                 # Environment variables template
├── docker-compose.yml           # Docker Compose configuration
├── Dockerfile                   # Production Docker image
├── Dockerfile.dev               # Development Docker image with hot reload
├── go.mod                       # Go module definition
├── Taskfile.yml                 # Task runner configuration
└── README.md                    # This file

API Endpoints and Authentication

The server exposes public endpoints (/health, /api/funk/sign-up and /api/funk/login) for health checks and authentication, and protected endpoints for function management and execution.

Trezo Funk uses API key (administration) or JWT token (function calls) authentication to protect API endpoints. Requests must include an Authorization header with a Bearer token.

Authentication can be disabled for testing by setting DISABLE_AUTH=true. Never do this in production.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

AGPL 3