Сервисы

Свой сервис

Сервис — обычный класс с двумя методами. Здесь мы шаг за шагом напишем самый простой: маленький сервер, который раздаёт файлы из папки.

Контракт ServiceМетоды component() · image()Объявление $components->service()

Что такое свой сервис и зачем

Что это. Класс вашего проекта, который реализует интерфейс Service.

Проблема. Готового сервиса для нужной программы может не быть.

Решение. Описать программу один раз в классе — и объявлять её одной строкой, в этом проекте и в следующих.

Service

У интерфейса два метода:

Метод Что отвечает
component() как запускать программу: команда, имя, проверки
image() что ей нужно в образе: пакеты, папки. Если всё уже есть — пусто

Шаг 1. Класс

Возьмём программу, которая уже есть в любом образе с PHP, — встроенный сервер php -S. Он раздаёт файлы из папки public/ на порту 8080:

main/Services/StaticFiles.php
namespace Main\Services;

use Flytachi\Winter\Kernel\App\Component;
use Flytachi\Winter\Kernel\App\Service;
use Flytachi\Winter\Kernel\App\ServiceImage;

final class StaticFiles implements Service
{
  public function component(): Component
  {
      return Component::command(['php', '-S', '0.0.0.0:8080', '-t', 'public'], 'static-files');
  }

  public function image(): ServiceImage
  {
      return new ServiceImage();   // PHP is already in the image
  }
}
  • Component::command() — внешняя программа: сначала сама программа, потом её аргументы, вторым параметром — имя для логов.
  • image() пустой: ставить ничего не нужно.

Шаг 2. Объявить

bootstrap.php
use Main\Services\StaticFiles;

protected static function components(Components $components): void
{
  $components->service(new StaticFiles());
}

Запускаем приложение — в логе:

text
Application up: http://0.0.0.0:8000 + [static-files]
static-files is up.
Http is up.

Файлы открываются: curl localhost:8080/hello.txt.

Сервис уже работает, но пока просто: он стартует одновременно с HTTP, а если упадёт — приложение остановится целиком (сервис по умолчанию важный, critical, и перезапусков у него нет). Исправим это.

Шаг 3. Научить ждать и следить

Сейчас приложение считает сервис готовым сразу после запуска. Добавим три параметра:

main/Services/StaticFiles.php
public function component(): Component
{
  return Component::command(
      ['php', '-S', '0.0.0.0:8080', '-t', 'public'],
      'static-files',
      priority: Priority::High,           // start before HTTP, stop after it
      ready: 'tcp://127.0.0.1:8080',      // ready once the port answers
      alive: 'tcp://127.0.0.1:8080',      // then keep checking it
      retries: 3,                         // restart it if it crashes
  );
}
Параметр Что даёт
priority: Priority::High сервис стартует раньше HTTP и останавливается после него
ready остальные ждут, пока порт не ответит
alive порт проверяется и дальше; завис — сервис перезапускается
retries сколько раз перезапустить после падения

Теперь лог такой — сервис поднимается первым, а после падения возвращается:

text
Application starting High: static-files
static-files is up.
Application starting Normal: Http
Http is up.
static-files crashed: killed by signal 15; restart 1 of 3 in 1s.
static-files is up.

Все параметры — на странице компонентов.

Шаг 4. Параметры через конструктор

Порт и папку удобно передавать снаружи:

main/Services/StaticFiles.php
namespace Main\Services;

use Flytachi\Winter\Kernel\App\Component;
use Flytachi\Winter\Kernel\App\Priority;
use Flytachi\Winter\Kernel\App\Service;
use Flytachi\Winter\Kernel\App\ServiceImage;

final class StaticFiles implements Service
{
  public function __construct(
      private readonly int $port = 8080,
      private readonly string $dir = 'public',
  ) {
  }

  public function component(): Component
  {
      $check = "tcp://127.0.0.1:{$this->port}";

      return Component::command(
          ['php', '-S', "0.0.0.0:{$this->port}", '-t', $this->dir],
          'static-files',
          priority: Priority::High,
          ready: $check,
          alive: $check,
          retries: 3,
      );
  }

  public function image(): ServiceImage
  {
      return new ServiceImage();
  }
}
bootstrap.php
$components->service(new StaticFiles(port: 9000, dir: 'storage/files'));

Несколько советов

  1. new StaticFiles() без аргументов должен работать — умолчания делайте разумными.
  2. Проверка — лёгкая: открыт ли порт, отвечает ли ping. Не тяжёлый запрос.
  3. Сервисам, на которых держатся остальные, — Priority::High.
  4. Наружу — только если нужно. Сервису для своего кода хватит 127.0.0.1.

Дальше

  • Что нужно в образе — когда программы в образе нет и её надо поставить.
  • PostgreSQL — как выглядит готовый сервис из пакета.