Files
Speech/apps/api/internal/httpapi/server.go
T

527 lines
19 KiB
Go

package httpapi
import (
"context"
"encoding/base64"
"errors"
"io"
"log/slog"
"net/http"
"strings"
"time"
"unicode"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
"speech-learning-api/internal/services"
)
type DataStore interface {
GetUser(ctx context.Context, id string) (domain.User, error)
GetPrimaryProfile(ctx context.Context, userID string) (domain.LearnerProfile, error)
UpdatePreferences(ctx context.Context, userID, uiLanguage, targetLanguage, cefrLevel string, dailyGoalMinutes int) (domain.LearnerProfile, error)
ListLanguages(ctx context.Context) ([]domain.LanguageProfile, error)
GetLanguage(ctx context.Context, code string) (domain.LanguageProfile, error)
NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error)
SaveGeneratedExercise(ctx context.Context, userID string, generated domain.GeneratedExercise) (domain.Lesson, domain.Exercise, error)
GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error)
SaveAttempt(ctx context.Context, attempt domain.Attempt) (domain.Attempt, error)
Progress(ctx context.Context, userID string, limit int) (domain.ProgressSummary, error)
AdminOverview(ctx context.Context) (domain.AdminOverview, error)
AdminUsers(ctx context.Context, search string, page int) (domain.AdminUserPage, error)
CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error)
SaveConversationTurn(ctx context.Context, turn domain.ConversationTurn) (domain.ConversationTurn, error)
DebugStatus(ctx context.Context) domain.DebugDBStatus
}
type Server struct {
cfg config.Config
logger *slog.Logger
store DataStore
auth *services.AuthService
speech services.SpeechService
teacher services.TeacherAgent
started time.Time
}
func NewServer(cfg config.Config, logger *slog.Logger, store DataStore, auth *services.AuthService, speech services.SpeechService, teacher services.TeacherAgent) *Server {
return &Server{cfg: cfg, logger: logger, store: store, auth: auth, speech: speech, teacher: teacher, started: time.Now()}
}
func (s *Server) Routes() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /health", s.health)
mux.HandleFunc("POST /auth/register", s.register)
mux.HandleFunc("POST /auth/login", s.login)
mux.HandleFunc("POST /auth/logout", s.logout)
mux.Handle("GET /me", s.requireAuth(http.HandlerFunc(s.me)))
mux.Handle("PATCH /me/preferences", s.requireAuth(http.HandlerFunc(s.updatePreferences)))
mux.Handle("GET /languages", s.requireAuth(http.HandlerFunc(s.languages)))
mux.Handle("GET /languages/{code}/voices", s.requireAuth(http.HandlerFunc(s.languageVoices)))
mux.Handle("GET /dashboard", s.requireAuth(http.HandlerFunc(s.dashboard)))
mux.Handle("GET /progress", s.requireAuth(http.HandlerFunc(s.progress)))
mux.Handle("POST /lessons/next", s.requireAuth(http.HandlerFunc(s.nextLesson)))
mux.Handle("GET /practice/exercises/{id}/audio", s.requireAuth(http.HandlerFunc(s.exerciseAudio)))
mux.Handle("POST /practice/attempts", s.requireAuth(http.HandlerFunc(s.createAttempt)))
mux.Handle("POST /conversation/start", s.requireAuth(http.HandlerFunc(s.startConversation)))
mux.Handle("POST /conversation/{id}/turn", s.requireAuth(http.HandlerFunc(s.conversationTurn)))
mux.Handle("GET /admin/overview", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminOverview))))
mux.Handle("GET /admin/users", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminUsers))))
if s.cfg.DebugEnabled {
mux.Handle("GET /debug/status", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugStatus))))
mux.Handle("GET /debug/db", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugDB))))
mux.Handle("GET /debug/flowise", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugFlowise))))
mux.Handle("GET /debug/azure", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugAzure))))
mux.Handle("GET /debug/runtime", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugRuntime))))
}
return s.requestID(s.requestLogging(s.cors(mux)))
}
func (s *Server) health(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}
func (s *Server) register(w http.ResponseWriter, r *http.Request) {
var req struct {
Email string `json:"email"`
Password string `json:"password"`
UILanguage string `json:"ui_language"`
TargetLanguage string `json:"target_language"`
DailyGoalMinutes int `json:"daily_goal_minutes"`
}
if err := decodeJSON(r, &req); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
result, err := s.auth.Register(r.Context(), req.Email, req.Password, req.UILanguage, req.TargetLanguage, req.DailyGoalMinutes)
if err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
writeJSON(w, http.StatusCreated, result)
}
func (s *Server) login(w http.ResponseWriter, r *http.Request) {
var req struct {
Email string `json:"email"`
Password string `json:"password"`
}
if err := decodeJSON(r, &req); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
result, err := s.auth.Login(r.Context(), req.Email, req.Password)
if err != nil {
status := http.StatusInternalServerError
if errors.Is(err, services.ErrInvalidCredentials) {
status = http.StatusUnauthorized
}
writeError(w, status, err)
return
}
writeJSON(w, http.StatusOK, result)
}
func (s *Server) logout(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}
func (s *Server) me(w http.ResponseWriter, r *http.Request) {
user, err := s.store.GetUser(r.Context(), currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
profile, err := s.store.GetPrimaryProfile(r.Context(), user.ID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"user": user, "profile": profile})
}
func (s *Server) updatePreferences(w http.ResponseWriter, r *http.Request) {
var req struct {
UILanguage string `json:"ui_language"`
TargetLanguage string `json:"target_language"`
CEFRLevel string `json:"cefr_level"`
DailyGoalMinutes int `json:"daily_goal_minutes"`
}
if err := decodeJSON(r, &req); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
profile, err := s.store.UpdatePreferences(r.Context(), currentUserID(r), req.UILanguage, req.TargetLanguage, valueOr(req.CEFRLevel, "A1"), req.DailyGoalMinutes)
if err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
writeJSON(w, http.StatusOK, profile)
}
func (s *Server) languages(w http.ResponseWriter, r *http.Request) {
languages, err := s.store.ListLanguages(r.Context())
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
writeJSON(w, http.StatusOK, languages)
}
func (s *Server) languageVoices(w http.ResponseWriter, r *http.Request) {
lang, err := s.store.GetLanguage(r.Context(), r.PathValue("code"))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"code": lang.Code, "voices": lang.Voices, "default_voice": lang.DefaultTTSVoice})
}
func (s *Server) dashboard(w http.ResponseWriter, r *http.Request) {
userID := currentUserID(r)
user, err := s.store.GetUser(r.Context(), userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
profile, err := s.store.GetPrimaryProfile(r.Context(), userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
progress, err := s.store.Progress(r.Context(), userID, 5)
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, nil)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
writeJSON(w, http.StatusOK, domain.Dashboard{
User: user, Profile: profile, Progress: progress, NextLesson: lesson, NextExercise: exercise,
})
}
func (s *Server) progress(w http.ResponseWriter, r *http.Request) {
progress, err := s.store.Progress(r.Context(), currentUserID(r), 20)
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
writeJSON(w, http.StatusOK, progress)
}
func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
userID := currentUserID(r)
var req struct {
PreviousExerciseID string `json:"previous_exercise_id"`
RecentExerciseIDs []string `json:"recent_exercise_ids"`
}
if err := decodeJSON(r, &req); err != nil && !errors.Is(err, io.EOF) {
writeError(w, http.StatusBadRequest, err)
return
}
recentIDs := req.RecentExerciseIDs
if req.PreviousExerciseID != "" && (len(recentIDs) == 0 || recentIDs[len(recentIDs)-1] != req.PreviousExerciseID) {
recentIDs = append(recentIDs, req.PreviousExerciseID)
}
if len(recentIDs) > 3 {
writeError(w, http.StatusBadRequest, errors.New("at most three recent exercises are allowed"))
return
}
avoidReferenceTexts := make([]string, 0, len(recentIDs))
for _, id := range recentIDs {
previous, err := s.store.GetExercise(r.Context(), id, userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
avoidReferenceTexts = append(avoidReferenceTexts, previous.TargetText)
}
user, err := s.store.GetUser(r.Context(), userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
profile, err := s.store.GetPrimaryProfile(r.Context(), userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
progress, err := s.store.Progress(r.Context(), userID, 10)
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, avoidReferenceTexts)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"lesson": lesson, "exercise": exercise})
}
func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profile domain.LearnerProfile, progress domain.ProgressSummary, avoidReferenceTexts []string) (domain.Lesson, domain.Exercise, error) {
avoidReferenceText := ""
if len(avoidReferenceTexts) > 0 {
avoidReferenceText = avoidReferenceTexts[len(avoidReferenceTexts)-1]
}
generated, err := s.teacher.NextExercise(ctx, domain.GeneratedExerciseRequest{
UserID: user.ID,
Profile: profile,
Progress: progress,
TargetLanguage: profile.TargetLanguage,
CEFRLevel: profile.CEFRLevel,
UILanguage: user.UILanguage,
SessionID: flowiseSessionID(user.ID, profile.TargetLanguage, "practice"),
RecentWeakWords: progress.WeakWords,
PreferredType: "repeat_sentence",
AvoidReferenceText: avoidReferenceText,
AvoidReferenceTexts: avoidReferenceTexts,
})
if err == nil && generated.Source == "flowise" && strings.TrimSpace(generated.ReferenceText) != "" {
lesson, exercise, saveErr := s.store.SaveGeneratedExercise(ctx, user.ID, generated)
if saveErr == nil {
s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID)
return lesson, exercise, nil
}
s.logger.Warn("saving generated exercise failed, using seed fallback", "error", saveErr)
}
if err != nil {
s.logger.Warn("flowise next exercise failed, using seed fallback", "error", err)
}
lesson, exercise, err := s.store.NextLessonAndExercise(ctx, profile, avoidReferenceTexts...)
if err == nil {
s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID)
}
return lesson, exercise, err
}
func (s *Server) exerciseAudio(w http.ResponseWriter, r *http.Request) {
exercise, err := s.store.GetExercise(r.Context(), r.PathValue("id"), currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
mode := r.URL.Query().Get("mode")
if mode == "" {
mode = "normal"
}
if mode != "normal" && mode != "slow" && mode != "focus" {
writeError(w, http.StatusBadRequest, errors.New("unsupported audio mode"))
return
}
focusWord := r.URL.Query().Get("word")
if mode == "focus" {
focusWord = exerciseFocusWord(exercise.TargetText, focusWord)
if focusWord == "" {
writeError(w, http.StatusBadRequest, errors.New("word must occur in the exercise sentence"))
return
}
} else if focusWord != "" {
writeError(w, http.StatusBadRequest, errors.New("word is only supported in focus mode"))
return
}
language, err := s.store.GetLanguage(r.Context(), exercise.TargetLanguage)
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
audio, mime, err := s.speech.SynthesizeExercise(r.Context(), language.AzureLocale, language.DefaultTTSVoice, exercise.TargetText, mode, focusWord)
if err != nil {
writeError(w, http.StatusBadGateway, err)
return
}
if len(audio) == 0 {
writeError(w, http.StatusServiceUnavailable, errors.New("audio is unavailable"))
return
}
w.Header().Set("Content-Type", mime)
w.Header().Set("Cache-Control", "private, no-store")
w.WriteHeader(http.StatusOK)
_, _ = w.Write(audio)
}
func exerciseFocusWord(sentence, requested string) string {
requested = strings.TrimFunc(strings.TrimSpace(requested), func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsNumber(r) })
if requested == "" {
return ""
}
for _, token := range strings.Fields(sentence) {
word := strings.TrimFunc(token, func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsNumber(r) })
if strings.EqualFold(word, requested) {
return word
}
}
return ""
}
func (s *Server) createAttempt(w http.ResponseWriter, r *http.Request) {
if err := r.ParseMultipartForm(24 << 20); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
exerciseID := r.FormValue("exercise_id")
exercise, err := s.store.GetExercise(r.Context(), exerciseID, currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
file, header, err := r.FormFile("audio")
if err != nil {
writeError(w, http.StatusBadRequest, errors.New("audio file is required"))
return
}
defer file.Close()
audio, err := io.ReadAll(io.LimitReader(file, 20<<20))
if err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
contentType := header.Header.Get("Content-Type")
if contentType == "" {
contentType = "audio/wav"
}
result, err := s.speech.AssessPronunciation(r.Context(), services.PronunciationInput{
Audio: audio, ContentType: contentType, TargetText: exercise.TargetText, Locale: exercise.TargetLanguage,
})
if err != nil {
writeError(w, http.StatusBadGateway, err)
return
}
teacher, err := s.teacher.FeedbackForAttempt(r.Context(), exercise.TargetText, result, weakWords(result.WordScores))
if err != nil {
writeError(w, http.StatusBadGateway, err)
return
}
attempt, err := s.store.SaveAttempt(r.Context(), domain.Attempt{
UserID: currentUserID(r),
ExerciseID: exercise.ID,
TargetLanguage: exercise.TargetLanguage,
RecognizedText: result.RecognizedText,
OverallScore: result.OverallScore,
AccuracyScore: result.AccuracyScore,
FluencyScore: result.FluencyScore,
CompletenessScore: result.CompletenessScore,
ProsodyScore: result.ProsodyScore,
WordScores: result.WordScores,
TeacherFeedback: teacher.TeacherFeedback,
})
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
writeJSON(w, http.StatusCreated, map[string]any{"attempt": attempt, "teacher": teacher, "provider": result.Provider})
}
func (s *Server) startConversation(w http.ResponseWriter, r *http.Request) {
profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
session, err := s.store.CreateConversationSession(r.Context(), currentUserID(r), profile.TargetLanguage, profile.CEFRLevel)
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
teacher, err := s.teacher.StartConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel)
if err != nil {
writeError(w, http.StatusBadGateway, err)
return
}
lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage)
audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText))
turn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: session.ID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)})
writeJSON(w, http.StatusCreated, map[string]any{
"session": session,
"turn": turn,
"teacher": teacher,
"audio": encodeAudio(audio, mime),
})
}
func (s *Server) conversationTurn(w http.ResponseWriter, r *http.Request) {
var req struct {
Text string `json:"text"`
}
if err := decodeJSON(r, &req); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
sessionID := r.PathValue("id")
userTurn, err := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "learner", Text: req.Text})
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
teacher, err := s.teacher.ContinueConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel, req.Text)
if err != nil {
writeError(w, http.StatusBadGateway, err)
return
}
lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage)
audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText))
teacherTurn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)})
writeJSON(w, http.StatusOK, map[string]any{
"user_turn": userTurn,
"teacher_turn": teacherTurn,
"teacher": teacher,
"audio": encodeAudio(audio, mime),
})
}
func weakWords(words []domain.WordScore) []domain.WordScore {
out := make([]domain.WordScore, 0)
for _, word := range words {
if word.Accuracy < 75 {
out = append(out, word)
}
}
return out
}
func encodeAudio(audio []byte, mime string) map[string]string {
if len(audio) == 0 {
return nil
}
return map[string]string{
"mime_type": mime,
"base64": base64.StdEncoding.EncodeToString(audio),
}
}
func firstNonEmpty(values ...string) string {
for _, value := range values {
if strings.TrimSpace(value) != "" {
return value
}
}
return ""
}
func flowiseSessionID(userID, targetLanguage, scope string) string {
parts := []string{strings.TrimSpace(userID), strings.TrimSpace(targetLanguage), strings.TrimSpace(scope)}
for i, part := range parts {
parts[i] = strings.ReplaceAll(part, " ", "_")
}
return strings.Join(parts, ":")
}
func valueOr(value, fallback string) string {
if strings.TrimSpace(value) == "" {
return fallback
}
return value
}