KaisarCode

miniserv es un servidor web HTTP/1.1 de archivos estáticos, minimalista, portátil y conforme a POSIX, escrito en C. Diseñado para ser simple, auditable y sin dependencias, está implementado únicamente con C estándar y APIs POSIX.

Repositorio

https://github.com/kaisarcode/miniserv

Características

• Conexiones Keep-Alive (HTTP/1.1)
• Soporte para rangos y contenido parcial (RFC 7233)
• Métodos HEAD y GET
• Pool de hilos con cola de peticiones segura (pthread)
• I/O completamente POSIX: poll, read, write, lseek, socket
• Detección estática de MIME types (incluyendo .ico)
• Apagado limpio con señales SIGINT o SIGTERM

---

Arquitectura Técnica

miniserv utiliza un pool fijo de hilos trabajadores. Cada hilo usa poll(2) para esperar datos del cliente y servir solicitudes directamente.

Los descriptores de archivo se distribuyen entre hilos mediante una cola circular (fd_queue_t), sincronizada con pthread_mutex_t y pthread_cond_t, asegurando concurrencia eficiente con mínimo locking.

Todas las llamadas del sistema son conformes a POSIX.1-2008, sin extensiones específicas como epoll o kqueue.

---

Compilación

cd src
make

El binario resultante se generará como ./miniserv en la raíz del proyecto.

Instalación

sudo make install

Instala:

• Binario → /usr/local/bin/miniserv
• Manpage → /usr/local/share/man/man1/miniserv.1

Para desinstalar:

sudo make uninstall

---

Uso

Modo básico

./miniserv 8080 ./www

Sintaxis completa

miniserv [PUERTO] [DOCUMENT_ROOT] [THREADS] [TIMEOUT] [MAX_KEEPALIVE]

Valores por defecto:

• Puerto: 8080
• Hilos: 4
• Timeout Keep-Alive: 5s
• Máx. solicitudes Keep-Alive: 100

Ejemplo

./miniserv 8080 /var/www 8 10 200

Después abre tu navegador en:

http://localhost:8080/

---

Soporte HTTPS

miniserv no implementa SSL/TLS internamente, por diseño. Para HTTPS, puede ejecutarse detrás de un proxy TLS como stunnel, nginx, caddy o haproxy.

Ejemplo con stunnel:

[https]
accept = 443
connect = 127.0.0.1:8080
cert = /ruta/a/server.pem

Luego inicia miniserv normalmente:

./miniserv 8080 ./www
sudo stunnel stunnel-miniserv.conf

Esto habilita HTTPS sin comprometer la portabilidad y simplicidad de miniserv.

---

Historia

miniserv fue creado originalmente en 2013 por KaisarCode, como un experimento personal inspirado en el libro "Lenguaje C" de Fco. Javier Ceballos.

En 2025 fue reescrito desde cero como un servidor modular, limpio y completamente POSIX.1-2008, sirviendo como referencia didáctica y base práctica para proyectos de red en C.