Healthcheck

Application Kit ships a simple TCP healthcheck designed to replace hand-maintained healthcheck.sh shell scripts in containers.

Why?

Bender configures every service with a healthcheck that runs /usr/src/app/healthcheck.sh. Each application maintains its own script, typically something like:

#!/usr/bin/env bash
set -e
curl -f http://localhost:8000/health/ || exit 1

This means installing curl or nc in production images, writing fragile shell one-liners, and dealing with inconsistent behavior across base images (nc flags vary between busybox, GNU, and nmap variants).

Since Application Kit is already installed in every service, you can replace the shell script with a single line that has zero extra dependencies.

Usage

In your healthcheck.sh:

#!/usr/bin/env bash
exec python -m application_kit.healthcheck

By default it connects to 127.0.0.1:8000. Pass host and port as positional arguments to override:

#!/usr/bin/env bash
exec python -m application_kit.healthcheck 0.0.0.0 8080

The command exits with code 0 on success and 1 on failure — exactly what Docker expects.

How it Works

It opens a TCP socket to the target host/port with a 1-second timeout. No HTTP request is made — it only checks that the server is listening and accepting connections. This is intentional: a TCP check is fast, has no side effects, and works regardless of your application's routing or middleware.

API Reference

application_kit.healthcheck

Simple TCP healthcheck for container health probes.

This module provides a lightweight healthcheck that can be used instead of installing netcat or curl in containers.

Usage

python -m application_kit.healthcheck [host][port]

Examples:

python -m application_kit.healthcheck # Check 127.0.0.1:8000 python -m application_kit.healthcheck 0.0.0.0 8080 # Check 0.0.0.0:8080

check_tcp_connection

check_tcp_connection(
    host=DEFAULT_HOST, port=DEFAULT_PORT, timeout=1.0
)

Check if a TCP connection can be established.

PARAMETER	DESCRIPTION
host	The host to connect to. TYPE: str DEFAULT: DEFAULT_HOST
port	The port to connect to. TYPE: int DEFAULT: DEFAULT_PORT
timeout	Connection timeout in seconds. TYPE: float DEFAULT: 1.0

RETURNS	DESCRIPTION
bool	True if connection succeeded, False otherwise.

Source code in application_kit/healthcheck.py

def check_tcp_connection(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, timeout: float = 1.0) -> bool:
    """Check if a TCP connection can be established.

    Args:
        host: The host to connect to.
        port: The port to connect to.
        timeout: Connection timeout in seconds.

    Returns:
        True if connection succeeded, False otherwise.
    """
    client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    client.settimeout(timeout)
    try:
        client.connect((host, port))
        return True
    except Exception:
        return False
    finally:
        client.close()

main

main(args=None)

Run the health check.

PARAMETER	DESCRIPTION
args	Command line arguments. If None, uses sys.argv[1:]. TYPE: list[str] | None DEFAULT: None

RETURNS	DESCRIPTION
int	0 if healthy, 1 if unhealthy.

Source code in application_kit/healthcheck.py

def main(args: list[str] | None = None) -> int:
    """Run the health check.

    Args:
        args: Command line arguments. If None, uses sys.argv[1:].

    Returns:
        0 if healthy, 1 if unhealthy.
    """
    if args is None:
        args = sys.argv[1:]

    host = args[0] if len(args) > 0 else DEFAULT_HOST
    port = int(args[1]) if len(args) > 1 else DEFAULT_PORT

    if check_tcp_connection(host, port):
        return 0
    else:
        print("server/socket must have died...time to hop off")
        return 1