worktable.cc/pkgz/httpserv

httpserv

Небольшой пакет для Go-приложений с HTTP-сервером на базе Echo. Пакет проверяет адрес прослушивания, устанавливает восстановление после паники и обработку ошибок. Контекст управляет завершением сервера; маршруты и middleware регистрируются через Echo.

Путь импорта: worktable.cc/pkgz/httpserv. Имя Go-пакета: httpserv.

Установка

Требуется Go 1.27.3 или новее.

Для маршрутизации и запуска сервера используется github.com/labstack/echo/v5. Зависимость устанавливается вместе с пакетом; её версия указана в go.mod.

После публикации модуля по его пути:

go get worktable.cc/pkgz/httpserv

HTTP-сервер

package main

import (
	"context"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"

	"github.com/labstack/echo/v5"
	"worktable.cc/pkgz/httpserv"
)

func main() {
	ctx, stop := signal.NotifyContext(
		context.Background(),
		os.Interrupt,
		syscall.SIGTERM,
	)
	defer stop()

	server, err := httpserv.New(
		"127.0.0.1:8080",
		httpserv.Logger(slog.Default()),
	)
	if err != nil {
		panic(err)
	}

	server.Echo().GET("/health", func(c *echo.Context) error {
		return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
	})

	if err := server.Start(ctx); err != nil {
		panic(err)
	}
}

Start блокирует текущую горутину, пока сервер не завершится или переданный контекст не будет отменён. После отмены контекста Echo прекращает принимать новые соединения и ожидает завершения активных запросов. В используемой версии Echo ожидание завершения активных запросов по умолчанию ограничено 10 секундами.

API

Элемент	Назначение
Server	HTTP-сервер с доступом к Echo
Config	Конфигурация сервера, заполняемая функциями опций
Option	Функция настройки func(*Config) error
New(address, opts...)	Проверяет конфигурацию и создаёт сервер
(*Server).Echo()	Возвращает экземпляр Echo для настройки маршрутов
(*Server).Start(ctx)	Запускает сервер и связывает его жизненный цикл с контекстом
ValidateAddress(address)	Проверяет канонический адрес IPv4:порт
Logger(log)	Устанавливает *slog.Logger
BeforeServeFunc(fn)	Настраивает *http.Server перед запуском
HTTPErrorJSONHandler()	Создаёт JSON-обработчик HTTP-ошибок
HTTPErrorStringHandler()	Создаёт текстовый обработчик HTTP-ошибок
GroupErrorHandler(handler)	Применяет отдельный обработчик ошибок через middleware

Адрес прослушивания

New принимает адрес только в каноническом формате IPv4:порт, например:

127.0.0.1:8080
0.0.0.0:8080
192.168.1.10:443

Имена хостов, IPv6, нулевой порт и неканонические записи отклоняются:

localhost:8080   # имя хоста
[::1]:8080       # IPv6
127.0.0.1:0      # нулевой порт
127.0.0.1:080    # неканоническая запись порта

Допустимы порты от 1 до 65535. Функцию ValidateAddress можно использовать для отдельной проверки адреса до создания сервера.

Настройка

Опции передаются в New и применяются по порядку. Опция со значением nil не изменяет конфигурацию.

Логгер

server, err := httpserv.New(
	"0.0.0.0:8080",
	httpserv.Logger(slog.Default()),
)

Без Logger используется slog.Logger с slog.DiscardHandler: записи логов отбрасываются. Logger(nil) также оставляет этот логгер без изменений.

Настройка http.Server

BeforeServeFunc вызывается после открытия слушающего сокета, непосредственно перед началом обслуживания запросов. Через неё можно установить тайм-ауты и лимиты стандартного http.Server (в примере требуется импорт time):

server, err := httpserv.New(
	"0.0.0.0:8080",
	httpserv.BeforeServeFunc(func(server *http.Server) error {
		server.ReadHeaderTimeout = 5 * time.Second
		server.IdleTimeout = 60 * time.Second
		server.MaxHeaderBytes = 1 << 20

		return nil
	}),
)

Если функция возвращает ошибку, слушающий сокет закрывается, обслуживание запросов не начинается, а Start возвращает эту ошибку.

Обработка ошибок

По умолчанию сервер использует HTTPErrorJSONHandler. Ошибка обработчика превращается в ответ вида:

{"error":"Not Found"}

Код ответа извлекается через echo.StatusCode из ошибки, реализующей echo.HTTPStatusCoder, включая *echo.HTTPError. Если код равен нулю, используется 500 Internal Server Error. Если echo.HTTPError содержит непустое сообщение, оно отправляется клиенту; внутренняя причина обёрнутой ошибки в ответ не попадает.

Для HEAD возвращается только статус без тела. Уже отправленный ответ обработчик не изменяет.

Доступны два формата:

Обработчик	Тело ответа
HTTPErrorJSONHandler()	JSON {"error":"сообщение"}
HTTPErrorStringHandler()	строка сообщение

Ошибки со статусом 5xx записываются на уровне ERROR. Запись содержит HTTP-метод, путь, статус и исходную ошибку. Ошибки записи ответа также логируются.

Отдельный формат для группы маршрутов

GroupErrorHandler позволяет группе Echo использовать собственный обработчик ошибок:

api := server.Echo().Group("/api")
api.Use(
	httpserv.GroupErrorHandler(
		httpserv.HTTPErrorStringHandler(),
	),
)

Middleware перехватывает ошибку вложенного обработчика, передаёт её указанному echo.HTTPErrorHandler и возвращает nil, поэтому глобальный обработчик Echo повторно не вызывается. Переданный обработчик не должен быть nil.

Стандартная конфигурация

New создаёт Echo со следующими настройками:

• middleware Recover восстанавливает выполнение после паники в обработчике;
• глобальный обработчик ошибок — HTTPErrorJSONHandler();
• баннер и сообщение с адресом при запуске скрыты;
• логгер по умолчанию отбрасывает записи.

Метод Echo возвращает исходный *echo.Echo. Через него регистрируются маршруты и middleware, а также настраиваются binder, renderer и другие компоненты Echo.

Границы реализации

Пакет принимает только канонические адреса IPv4:порт. Имена хостов, IPv6 и автоматический выбор порта через :0 не поддерживаются. Проверка адреса не гарантирует, что он доступен на текущей машине или что порт свободен: слушающий сокет открывается только при Start.

Пакет запускает HTTP-сервер без TLS. Сигналы процесса не обрабатываются автоматически: приложение создаёт контекст и передаёт его в Start. Настройки маршрутов, middleware и компонентов Echo следует задавать до запуска сервера.

Разработка и проверка

Из корня модуля:

go test ./...
go vet ./...

Тесты проверяют формат адресов, применение опций, JSON- и текстовые ответы на ошибки, обработку ошибок группы маршрутов, ответы на HEAD, сохранение уже отправленного ответа, логирование и отказ при запуске неинициализированного сервера. Запуск слушающего сокета и завершение сервера по отмене контекста этими тестами не проверяются.