transcriber/internal/controller/http/transcribe.go

package http

import (
	"context"
	"errors"
	"log/slog"
	"net/http"
	"time"

	"github.com/pocketbase/pocketbase/apis"
	"github.com/pocketbase/pocketbase/core"
	"github.com/pocketbase/pocketbase/tools/router"

	"git.vakhrushev.me/av/transcriber/internal/adapter/repo/pocketbase/migrations"
	"git.vakhrushev.me/av/transcriber/internal/contract"
	"git.vakhrushev.me/av/transcriber/internal/entity"
	"git.vakhrushev.me/av/transcriber/internal/service"
)

type TranscribeHandler struct {
	jobRepo    contract.TranscriptJobRepository
	trsService *service.TranscribeService
	logger     *slog.Logger
}

func NewTranscribeHandler(jobRepo contract.TranscriptJobRepository, trsService *service.TranscribeService, logger *slog.Logger) *TranscribeHandler {
	if logger == nil {
		logger = slog.Default()
	}
	return &TranscribeHandler{jobRepo: jobRepo, trsService: trsService, logger: logger}
}

type CreateTranscribeJobResponse struct {
	JobID string `json:"job_id"`
	State string `json:"status"`
}

type GetTranscribeJobResponse struct {
	JobID             string    `json:"job_id"`
	State             string    `json:"status"`
	CreatedAt         time.Time `json:"created_at"`
	TranscriptionText *string   `json:"transcription_text,omitempty"`
}

// Register вешает маршруты сервиса на роутер хранилища. Порт у сервиса и у
// панели один, поэтому и роутер один; имена полей ответа и коды при переезде
// сохранены — публичный контракт API объявлен необратимым.
func (h *TranscribeHandler) Register(r *router.Router[*core.RequestEvent]) {
	api := r.Group("/api")

	// Оба адреса уходят за аутентификацию. Слой предъявления стоит перед
	// проверкой и действует только здесь: собственная поверхность хранилища под
	// него не подпадает, часть её защищена ровно тем, что браузер заголовка сам
	// не шлёт.
	api.Bind(SessionFromCookie())
	// Коллекция названа поимённо, а не оставлена умолчанию. Без имени проверка
	// пускает всякую учётную запись хранилища, включая владельца панели, — а
	// записи в коллекции пользователей у него нет, и владельцем записи он стать
	// не может. Отказ такому предъявителю обязан наступить здесь, до чтения
	// тела: позже пришлось бы убирать уже уложенный файл, а уборки файлов
	// сервис не умеет вовсе.
	api.Bind(apis.RequireAuth(migrations.UsersCollection))

	// Умолчание роутера хранилища — 32 МиБ на тело, и оно отсекало бы запись
	// раньше обработчика, без строки в журнале приёма. Приём размеру не судья,
	// поэтому предел тела равен потолку самой записи.
	api.POST("/audio", h.CreateTranscribeJob).Bind(apis.BodyLimit(entity.MaxRecordSize))
	api.GET("/status/{id}", h.GetTranscribeJobStatus)
}

func (h *TranscribeHandler) CreateTranscribeJob(e *core.RequestEvent) error {
	// Получаем файл из формы
	file, header, err := e.Request.FormFile("audio")
	if err != nil {
		return e.JSON(http.StatusBadRequest, map[string]string{"error": "No audio file provided"})
	}
	defer func() {
		if err := file.Close(); err != nil {
			h.logger.Error("Failed to close uploaded file", "error", err)
		}
	}()

	// Запись доехала целиком, поэтому задача заводится независимо от того,
	// дождётся ли отправитель ответа: на контексте запроса приём терял бы
	// полностью загруженную запись от одного обрыва соединения, а забрать
	// результат он может и позже — по `GET /status/{id}`. Значения контекста
	// (журнал запроса, сессия) при этом сохраняются, теряется только отмена.
	ctx := context.WithoutCancel(e.Request.Context())

	// Владелец берётся из предъявленной сессии и ниоткуда больше: владелец,
	// пришедший полем запроса, дал бы всякому вошедшему право завести запись на
	// чужое имя. Проверка предъявителя стоит слоем выше, поэтому здесь `e.Auth`
	// уже есть и принадлежит коллекции пользователей.
	job, err := h.trsService.CreateJobFromApi(ctx, file, header.Filename, e.Auth.Id)
	if err != nil {
		// Второй раз отказ не логируем: приём назван конвенцией логирующей
		// границей и уже написал о нём. Транспорт переводит ошибку в ответ.
		return e.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to create transcibe job"})
	}

	// Возвращаем успешный ответ
	return e.JSON(http.StatusCreated, CreateTranscribeJobResponse{
		JobID: job.Id,
		State: job.State,
	})
}

func (h *TranscribeHandler) GetTranscribeJobStatus(e *core.RequestEvent) error {
	jobID := e.Request.PathValue("id")

	// Чужая задача, задача без владельца и несуществующая отвечают одним и тем
	// же: хранилище отдаёт на все три ту же ошибку, а транспорт — тот же код и
	// то же тело. Различать их наружу нельзя — по разнице ответов перебирается
	// список заведённых задач.
	job, err := h.jobRepo.GetByID(jobID, e.Auth.Id)
	if err != nil {
		// Наружу ответ один на все исходы, а в журнал они идут по-разному.
		// «Задачи нет» и «задача чужая» — штатная работа разграничения, о ней
		// писать нечего; всё прочее — отказ хранилища, и без этой строки он
		// приходит отправителю как «вашей записи нет», а владелец сервиса об
		// аварии не узнаёт ниоткуда. Журнал читает владелец, а не тот, кто
		// перебирает, поэтому различать их здесь можно.
		var notFound *contract.JobNotFoundError
		if !errors.As(err, &notFound) {
			h.logger.Error("Failed to read transcribe job", "error", err, "job_id", jobID)
		}
		return e.JSON(http.StatusNotFound, map[string]string{"error": "Job not found"})
	}

	return e.JSON(http.StatusOK, GetTranscribeJobResponse{
		JobID:             job.Id,
		State:             job.State,
		CreatedAt:         job.CreatedAt,
		TranscriptionText: job.TranscriptionText,
	})
}