SlimFaas Documentation

SlimFaas is a lightweight, plug-and-play Function-as-a-Service (FaaS) platform designed for Kubernetes, Docker-Compose, or Podman-Compose. It focuses on an autoscaling-first design with several key capabilities:

• Two-Phase Autoscaling:
  • 0 → N (Wake-up): Driven by HTTP history, time-based schedules, and Kafka topic activity (via SlimFaas Kafka).
  • N → M (Scaling): Driven by Prometheus metrics using a built-in PromQL evaluator.
• Function Types: Supports both synchronous (HTTP) and asynchronous (queued) functions, as well as one-off, batch, and scheduled (cron) jobs.
• Data Management:
  • Data Sets (/data/sets): A Redis-like KV store for small JSON/blobs (max 1 MiB) with millisecond TTL and atomic counters.
  • Data Files (/data/files): Stream-first endpoints for ingesting and serving temporary files of any size.
• Internal Events: Built-in publish/subscribe mechanism to broadcast events to all replicas of a function without an external bus.
• Security: Supports private functions (cluster-only) and public functions (via Ingress/API Gateways).
• Observability: Built-in User Interface for monitoring functions, jobs, and queues, plus a "Mind Changer" REST API for inspecting state and waking functions on demand.

SlimData guarantees total order via the RAFT leader and preserves FIFO order for each individual producer.

Ordering Model

Each producer (identified by hostname and SlimData port) emits batches with the following metadata:

• ProducerId: Stable replica identity.
• GenerationId: Unique identifier for the current process lifetime.
• Sequence: A monotonic number for the producer's batches.
• RequestId: A stable identifier for the request, used to handle transport retries.
• Mutations: An ordered array of mutations, each with its own request ID.

Retry and Deduplication

To prevent duplicate operations (like double-incrementing a value) during network failures or leader changes:

1. The local FIFO worker retries the exact same serialized batch if a leader is unavailable; it will not skip to a later batch.
2. The state machine stores the last Sequence, RequestId, and Response for each producer in a replicated internal key.
3. If a batch is replayed (e.g., after a leader change where the original acknowledgement was lost), the state machine recognizes the duplicate and returns the cached response without re-applying the mutation.
4. Out-of-order or missing sequences are rejected to maintain integrity.

SlimFaas MCP allows you to dynamically map values from the MCP _meta object to outgoing HTTP headers. This is useful for clients (like Spring AI) that transmit authentication tokens via _meta instead of standard headers.

Configuration: Define the mapping in the McpMetaHeaderMapping section of appsettings.json:

{
  "McpMetaHeaderMapping": {
    "authToken": "Authorization",
    "xSessionId": "X-Session-Id"
  }
}

How it works: When a tool is called, the values in _meta are injected into the outgoing request headers.

• If the mapped header is Authorization, SlimFaas MCP automatically prepends Bearer if it is missing.
• This feature supports OAuth challenge compatibility: if _meta.authToken is mapped to Authorization, the 401 challenge is automatically bypassed.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_dashboard_policies",
    "arguments": {},
    "_meta": {
      "authToken": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
      "xSessionId": "abc-123"
    }
  }
}

Resulting Headers: Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI... X-Session-Id: abc-123

SlimFaas uses a two-tier decision process during each periodic tick of CheckScaleAsync:

1. HTTP/Schedule System (Tier 1): This system runs first and is the only mechanism that can propose a transition from 0 to > 0 replicas. It calculates a proposedReplicas value based on HTTP history, scheduled wake-up times, and dependency activity.
2. Prometheus-based System (Tier 2): This system only runs if currentReplicas > 0. It calculates desiredFromMetrics using the PromQL queries defined in your SlimFaas/Scale annotations.

Scale-to-Zero Logic

When ReplicasMin = 0, scaling to zero requires agreement between both systems:

• The HTTP/Schedule system must propose scaling down to 0 (due to inactivity).
• The Prometheus system must also return a value where desiredFromMetrics <= 0.
• If metrics still require capacity (desiredFromMetrics > 0), SlimFaas will maintain at least one replica (max(1, desiredFromMetrics)).

Multi-Trigger Logic

If multiple triggers are defined in the SlimFaas/Scale annotation, the final desiredReplicas is the maximum value produced by any individual trigger.

SlimFaas uses two complementary autoscaling systems to manage function replicas:

1. 0 → N scaling (Wake-up from zero): Driven by HTTP call history, scheduled wake-up times, and function dependencies (DependsOn). This is the only system capable of bringing a function from 0 replicas to a positive number.
2. N → M scaling (Prometheus AutoScaler): Driven by Prometheus metrics and PromQL. This system manages scaling when a function already has at least one pod (replicas > 0).

Scale-to-Zero Logic: If you want to scale to zero (ReplicasMin: "0"), the two systems must agree. If the Prometheus AutoScaler is enabled (via the SlimFaas/Scale annotation with triggers), it can "veto" a scale-down to zero if its metrics indicate capacity is still needed (desired > 0). To allow the HTTP/Schedule system to control scale-to-zero exclusively, set Triggers: [] in the SlimFaas/Scale annotation.

flowchart LR
  R[ReplicasService.CheckScaleAsync]
  SW[ScaleReplicasWorker]
  K8S[(Kubernetes API)]

  subgraph HTTP_history["HTTP history and Schedule (0->N)"]
    H["History HTTP (in-memory + DB)"] --> R
    SC[Schedule config] --> R
    DP[DependsOn] --> R
  end

  subgraph Prometheus["Prometheus AutoScaler (N->M)"]
    MSW[MetricsScrapingWorker] --> MS[Metrics store]
    MS --> PQ[PromQL evaluator]
    PQ --> AS[AutoScaler]
    AS --> ASS[AutoScalerStore]
  end

  SW --> R
  R -- scale 0->N / N->0 --> K8S
  R -- desiredReplicas N->M --> K8S

In native local mode, a function, Job, or scheduled Job can wait for an auxiliary process to be running before it starts. This is achieved by using the processes:<name> prefix within the SlimFaas/DependsOn annotation.

How it works:

• A process is considered "ready" as soon as the managed operating-system process is running.
• Functions waiting on a process dependency will not scale up until the process is running.
• Jobs will remain queued until the process dependency is running.
• Note: There is no health probe for auxiliary processes. If a process dies, functions that are already running will not automatically scale down.
• This mechanism is ignored by Docker and Kubernetes, allowing you to use the same annotation to combine deployed dependencies (e.g., orders-database) with local development replacements (e.g., processes:database-emulator).

functions:
  orders-api:
    annotations:
      SlimFaas/Function: "true"
      SlimFaas/DependsOn: "orders-database,processes:database-emulator"

processes:
  database-emulator:
    command: ["database-emulator", "--port", "{port}"]
    port: auto
    restartPolicy: always