SlimFaas Functions (Sync & Async)

SlimFaas offers two main ways to invoke functions: synchronous and asynchronous HTTP calls. Below is an overview of each.

---

1. Synchronous Functions

Synchronous calls block until the underlying function pod handles the request and returns a response.

• Route: GET/POST/PUT/... http://<slimfaas>/function/<functionName>/<path>

• Example: GET http://localhost:30021/function/fibonacci1/hello/guillaume → 200 (OK) with response from fibonacci1

If your function has scaled to zero, SlimFaas automatically wakes it up and waits until at least one replica is ready (subject to internal timeouts).

---

2. Asynchronous Functions

Asynchronous calls return immediately (HTTP 202 or 201), while SlimFaas queues the request and processes it in the background.

• Route: GET/POST/PUT/... http://<slimfaas>/async-function/<functionName>/<path>

• Example: GET http://localhost:30021/async-function/fibonacci1/hello/guillaume → 202 (Accepted), handled in background synchronous mode also allows:

• Limiting parallel requests via annotations (e.g., SlimFaas/NumberParallelRequest).

• Retry pattern on timeouts or specific HTTP status codes.

---

3. Wake Function

You can explicitly “wake up” a function without invoking a specific route:

• Route: GET http://<slimfaas>/wake-function/<functionName>

• Response: 204 (No Content)

This is handy if you want to ensure the function is running before real traffic arrives.

---

4. Listing Functions

SlimFaas exposes a route to check the readiness status of all registered functions:

• Route: GET http://<slimfaas>/status-functions

• Response: An array of objects with details like NumberReady, numberRequested, PodType, Visibility, etc.

[
    {
      "NumberReady": 1,
      "NumberRequested": 1,
      "PodType": "Deployment",
      "Visibility": "Public",
      "Name": "fibonacci1"
    },
    ...
]

5. Private vs. Public Functions

By default, functions are Public (accessible from anywhere). You can specify them as Private—restricting access to calls originating from within the same namespace.

metadata:
    annotations:
        SlimFaas/DefaultVisibility: "Private"
        # or define paths:
        SlimFaas/PathsStartWithVisibility: "Private:/mypath,Public:/otherpath"
        SlimFaas/DefaultTrusted: "Trusted"

This helps you control which services can call certain endpoints.

An Untrusted function will be considered as outside the namespace and will not be able to access Private actions. By default, a function is Trusted.

metadata:
    annotations:
        SlimFaas/DefaultTrusted: "Trusted" # Trusted or Untrusted

6. Function Configuration

You can fine-tune sync/async HTTP timeouts, retries, and more using JSON config in SlimFaas/Configuration:

{
  "DefaultSync": {
    "HttpTimeout": 120,
    "TimeoutRetries": [2,4,8],
    "HttpStatusRetries": [500,502,503]
  },
  "DefaultAsync": {
    "HttpTimeout": 120,
    "TimeoutRetries": [2,4,8],
    "HttpStatusRetries": [500,502,503]
  },
  "DefaultPublish": {
    "HttpTimeout": 120,
    "TimeoutRetries": [2,4,8],
    "HttpStatusRetries": [500,502,503]
  }
}

These settings let you define how aggressively to retry failing calls, which statuses to retry, and more.

---

7. The DependsOn Annotation

You can also add a DependsOn annotation to specify that your function should wait for certain other pods to be ready before it scales up from zero. For example:

metadata:
    annotations:
        SlimFaas/Function: "true"
        SlimFaas/ReplicasMin: "0"
        SlimFaas/ReplicasAtStart: "1"
        # ...
        SlimFaas/DependsOn: "mysql,fibonacci2"

• mysql and fibonacci2 are the names of other deployments/statefulsets in the same namespace.
• SlimFaas will not scale the current function (e.g., fibonacci1) unless all pods listed in DependsOn are in a ready state and meet their own minimum replicas.

This is useful in scenarios where your function must not start until a database or another dependent function is confirmed running.

8. Scheduling Function Wake-Up and Scale-Down

If you want your function to automatically wake at a specific time or change its scale-down timeout based on the time of day, use the SlimFaas/Schedule annotation with a JSON configuration. This feature is especially useful for workloads with predictable peak/off-peak hours.

Example Annotation

metadata:
  annotations:
    SlimFaas/Schedule: >
      {
        "TimeZoneID": "Europe/Paris",
        "Default": {
          "WakeUp": ["07:00"],
          "ScaleDownTimeout": [
            { "Time": "07:00", "Value": 20 },
            { "Time": "21:00", "Value": 10 }
          ]
        }
      }

Configuration Details

• TimeZoneID Defines which IANA time zone to use (e.g., "Europe/Paris"). You can see the full list of valid time zone IDs here: https://nodatime.org/TimeZones

• WakeUp An array of times (HH:mm) at which the function should be woken up automatically. For example, "07:00" means that each day at 07:00 local time, the function will scale to its ReplicasAtStart value (rather than remain at zero).

• ScaleDownTimeout An array of objects containing:

  • Time: A local time string (e.g., "07:00").
  • Value: The inactivity timeout (in seconds) that applies after this time.
    • For instance, {"Time":"07:00","Value":20} sets a 20-second inactivity timeout from 07:00 until another time checkpoint is reached.
    • {"Time":"21:00","Value":10} sets a 10-second inactivity timeout from 21:00 onward.

How It Works

1. At each specified time, SlimFaas updates the function’s wake-up behavior or scale-down timeout in accordance with the schedule.
2. Waking up a function ensures at least one replica is running at that time.
3. ScaleDownTimeout adjusts how quickly the function is allowed to scale back to zero if there is no traffic.

Example Use Case

• 07:00: Wake up the function to be immediately available for peak morning traffic. The inactivity timeout becomes 20 seconds. If no traffic arrives for 20 seconds, the function could scale back to zero.
• 21:00: Reduce the inactivity timeout to 10 seconds, allowing a quicker scale-down in the evening/off-peak period.

This scheduling feature helps you maintain availability during predictable high-demand periods while efficiently saving resources during low-demand times.

9. Key Annotations for Functions

Before you start calling functions, ensure you add the necessary annotations to your Kubernetes Deployments or StatefulSets:

• SlimFaas/Function: "true" Activates SlimFaas auto-scaling and routing for this pod. Without this annotation, SlimFaas will ignore the pod.

• SlimFaas/ReplicasMin: "0" The minimum number of replicas to maintain for the function. Setting 0 allows the function to scale down to zero after inactivity.

• SlimFaas/ReplicasAtStart: "1" The number of replicas to initially wake up to when traffic arrives or when manually woken. Typically set to 1.

• SlimFaas/TimeoutSecondBeforeSetReplicasMin: "300" The number of inactivity seconds after which the function will scale down to ReplicasMin. (Default is often 300 seconds.)

• SlimFaas/NumberParallelRequest: "10" The maximum number of concurrent requests allowed for all replicas. Additional requests will queue until a slot frees up.

• SlimFaas/NumberParallelRequestPerPod: "10": The maximum number of concurrent requests allowed per pod. Additional requests will queue until a slot frees up.

# Example snippet from a Deployment
metadata:
    annotations:
        SlimFaas/Function: "true"
        SlimFaas/ReplicasMin: "0"
        SlimFaas/ReplicasAtStart: "1"
        SlimFaas/TimeoutSecondBeforeSetReplicasMin: "300"
        SlimFaas/NumberParallelRequest: "10"
        SlimFaas/NumberParallelRequestPerPod: "10"

---

10. Asynchronous Function Execution: Control Callback Mode

SlimFaas supports asynchronous function execution, allowing a function pod to take control of when the final result is returned. This pattern is well suited for long-running tasks, external system calls, or workflows that cannot complete immediately.

How It Works

1. The client (or another service) sends a request to SlimFaas:

   POST /async-function/<function-name>/<path>
   

2. SlimFaas forwards the request to the function pod and attaches a header:

   SlimFaas-Element-Id: <generated-id>
   

3. If the function wants to run control the callback, it must explicitly:

   • Return HTTP 202 Accepted instead of a final result.
   • Take responsibility for sending a callback when the result is ready.

   Returning 202 is the key trigger that enables callback mode.

4. When the function completes its work:

   • On success:

     POST /async-function-callback/<function-name>/<SlimFaas-Element-Id>/success
     

   • On failure:

     POST /async-function-callback/<function-name>/<SlimFaas-Element-Id>/error
     

5. If the timeout configured in SlimFaas expires before any callback is received, the execution is marked as failed.

Sequence Example

sequenceDiagram
    participant Client
    participant SlimFaas
    participant Function as Function Pod (e.g., Fibonacci)

    Client->>SlimFaas: POST /async-function/fibonacci
    SlimFaas->>Function: POST /fibonacci (with SlimFaas-Element-Id)
    Function-->>SlimFaas: HTTP 202 Accepted (async mode enabled)
    Note over Function: Function is now responsible for callback

    alt Success
        Function->>SlimFaas: POST /async-function-callback/fibonacci/<id>/success
        SlimFaas-->>Client: Final success response or notification
    else Error
        Function->>SlimFaas: POST /async-function-callback/fibonacci/<id>/error
        SlimFaas-->>Client: Error response or notification
    end

    SlimFaas-->>Client: Timeout if no callback received

Key Points

When to Use

Choose this mode when your function:

• Performs long-running or deferred processing
• Depends on external systems (queues, schedulers, batching, GPU workloads, etc.)
• Should not block the client during execution

---