fix: enable crash stack traces on Alpine, add test healthcheck

Worker SIGSEGV crashes in CI produce "(stack trace unavailable on musl)"
making root cause diagnosis impossible. Add libunwind-based backtrace
as a fallback on non-glibc systems, gated behind DEBUG_TOOLS=1 build
arg so production images stay lean.

Also add healthcheck to docker-compose.test.yml so the tester waits
for the proxy to be ready instead of using a hardcoded 10s sleep.

Author: dvershinin

.github/workflows/test.yml

@@ -65,7 +65,7 @@ jobs:
     - name: Install Dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y build-essential libssl-dev zlib1g-dev git curl vim-common python3 python3-pip python3-venv netcat-openbsd
+        sudo apt-get install -y build-essential libssl-dev zlib1g-dev git curl vim-common python3 python3-pip python3-venv netcat-openbsd libunwind-dev
         python3 -m venv .venv
         source .venv/bin/activate
         pip install requests telethon

Dockerfile

@@ -3,7 +3,10 @@ FROM alpine:3.21 AS builder
 
 # Install build dependencies
 # linux-headers: provides <linux/futex.h> used by mp-queue.c and jobs.c
-RUN apk add --no-cache build-base openssl-dev zlib-dev linux-headers git
+# DEBUG_TOOLS=1: adds libunwind for stack traces in crash dumps (test/CI only)
+ARG DEBUG_TOOLS=0
+RUN apk add --no-cache build-base openssl-dev zlib-dev linux-headers git \
+    $([ "$DEBUG_TOOLS" = "1" ] && echo "libunwind-dev")
 
 # Set working directory
 WORKDIR /src
@@ -24,7 +27,9 @@ FROM alpine:3.21
 # zlib: required by mtproto-proxy (-lz)
 # iproute2: ip command for local IP detection in NAT setup
 # ca-certificates: TLS certificate verification
-RUN apk add --no-cache curl ca-certificates openssl zlib iproute2
+ARG DEBUG_TOOLS=0
+RUN apk add --no-cache curl ca-certificates openssl zlib iproute2 \
+    $([ "$DEBUG_TOOLS" = "1" ] && echo "libunwind")
 
 # Create user for running the proxy
 RUN adduser -D -H -s /sbin/nologin mtproxy

Makefile

@@ -23,6 +23,14 @@ HOST_ARCH := $(shell arch)
 COMMON_CFLAGS := -O3 -std=gnu11 -Wall -fno-strict-aliasing -fno-strict-overflow -fwrapv -DAES=1 -DCOMMIT=\"${COMMIT}\" -DVERSION=\"${VERSION}\" -D_GNU_SOURCE=1 -D_FILE_OFFSET_BITS=64 -Wno-array-bounds -Wno-implicit-function-declaration
 COMMON_LDFLAGS := -ggdb -rdynamic -lm -lrt -lcrypto -lz -lpthread
 
+# Auto-detect libunwind for stack traces on musl/Alpine (test/CI builds)
+LIBUNWIND_CFLAGS := $(shell pkg-config --cflags libunwind 2>/dev/null)
+LIBUNWIND_LDFLAGS := $(shell pkg-config --libs libunwind 2>/dev/null)
+ifneq ($(LIBUNWIND_LDFLAGS),)
+COMMON_CFLAGS += -DHAVE_LIBUNWIND $(LIBUNWIND_CFLAGS)
+COMMON_LDFLAGS += $(LIBUNWIND_LDFLAGS)
+endif
+
 # Architecture-specific CFLAGS
 ifeq ($(HOST_ARCH), x86_64)
 CFLAGS := $(COMMON_CFLAGS) -mpclmul -march=core2 -mfpmath=sse -mssse3 $(BITNESS_FLAGS)

common/server-functions.c

@@ -37,6 +37,9 @@
 #include <errno.h>
 #ifdef __GLIBC__
 #include <execinfo.h>
+#elif defined(HAVE_LIBUNWIND)
+#define UNW_LOCAL_ONLY
+#include <libunwind.h>
 #endif
 #include <fcntl.h>
 #include <getopt.h>
@@ -176,6 +179,24 @@ void print_backtrace (void) {
   kwrite (2, "\n------- Stack Backtrace -------\n", 33);
   backtrace_symbols_fd (buffer, nptrs, 2);
   kwrite (2, "-------------------------------\n", 32);
+#elif defined(HAVE_LIBUNWIND)
+  kwrite (2, "\n------- Stack Backtrace -------\n", 33);
+  unw_cursor_t cursor;
+  unw_context_t context;
+  unw_getcontext (&context);
+  unw_init_local (&cursor, &context);
+  while (unw_step (&cursor) > 0) {
+    unw_word_t offset, pc;
+    char fname[128];
+    unw_get_reg (&cursor, UNW_REG_IP, &pc);
+    fname[0] = '\0';
+    unw_get_proc_name (&cursor, fname, sizeof (fname), &offset);
+    char line[256];
+    int len = snprintf (line, sizeof (line), "  %s (+0x%lx) [0x%lx]\n",
+                        fname[0] ? fname : "???", (long)offset, (long)pc);
+    if (len > 0) kwrite (2, line, len);
+  }
+  kwrite (2, "-------------------------------\n", 32);
 #else
   kwrite (2, "\n(stack trace unavailable on musl)\n", 35);
 #endif

tests/docker-compose.ip-acl-test.yml

@@ -3,6 +3,8 @@ services:
     build:
       context: ..
       dockerfile: Dockerfile
+      args:
+        DEBUG_TOOLS: "1"
     environment:
       - SECRET=${MTPROXY_SECRET}
       - PORT=8443

tests/docker-compose.multi-secret-test.yml

@@ -15,6 +15,8 @@ services:
     build:
       context: ..
       dockerfile: Dockerfile
+      args:
+        DEBUG_TOOLS: "1"
     environment:
       - SECRET=${MTPROXY_SECRET_1},${MTPROXY_SECRET_2}
       - PORT=8443

tests/docker-compose.test.yml

@@ -3,6 +3,8 @@ services:
     build:
       context: ..
       dockerfile: Dockerfile
+      args:
+        DEBUG_TOOLS: "1"
     ports:
       - "18443:8443"
       - "18888:8888"
@@ -14,11 +16,18 @@ services:
       - SECRET=${MTPROXY_SECRET}
       - PORT=8443
       - WORKERS=1
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:8888/stats || exit 1"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+      start_period: 5s
   tester:
     build: .
     environment:
       - MTPROXY_HOST=mtproxy
       - MTPROXY_PORT=8443
       - MTPROXY_STATS_PORT=8888
     depends_on:
-      - mtproxy
+      mtproxy:
+        condition: service_healthy

tests/docker-compose.tls-test.yml

@@ -15,6 +15,8 @@ services:
     build:
       context: ..
       dockerfile: Dockerfile
+      args:
+        DEBUG_TOOLS: "1"
     environment:
       - SECRET=${MTPROXY_SECRET:-d41d8cd98f00b204e9800998ecf8427e}
       - PORT=8443

tests/test_proxy.py

@@ -136,8 +136,8 @@ def check_upstream_connectivity():
     # Check upstream connectivity first (informational)
     check_upstream_connectivity()
 
-    # Give the proxy time to start and establish ME relay connections
-    time.sleep(10)
+    # Small buffer — docker-compose healthcheck ensures the proxy is ready
+    time.sleep(2)
 
     stats_ok = test_http_stats()
     metrics_ok = test_prometheus_metrics()