package httpapi import ( "context" "encoding/binary" "encoding/json" "errors" "io" "net/http" "strconv" "strings" "time" "speech-learning-api/internal/domain" "speech-learning-api/internal/services" "speech-learning-api/internal/store" ) func (s *Server) SetCourseEngine(engine *services.CourseEngine) { s.course = engine } func (s *Server) adaptiveProfile(w http.ResponseWriter, r *http.Request) (domain.LearnerProfile, bool) { if s.course == nil { writeError(w, http.StatusServiceUnavailable, errors.New("course engine unavailable")) return domain.LearnerProfile{}, false } p, err := s.courseProfile(r) if err != nil { writeError(w, http.StatusNotFound, err) return p, false } if p.CEFRLevel != "A1" { writeError(w, http.StatusBadRequest, errors.New("the adaptive course is available at A1")) return p, false } return p, true } func adaptiveError(w http.ResponseWriter, err error) { if errors.Is(err, store.ErrCourseVariantUnavailable) { writeJSON(w, http.StatusConflict, map[string]string{"error": err.Error(), "code": "course_variant_unavailable"}) return } status := http.StatusInternalServerError if errors.Is(err, store.ErrNotFound) { status = http.StatusNotFound } if errors.Is(err, store.ErrCourseConflict) { status = http.StatusConflict } if status == 500 { writeError(w, status, errors.New("Der Kursvorgang konnte nicht gespeichert oder geladen werden.")) } else { writeError(w, status, err) } } func adaptiveJSON(w http.ResponseWriter, r *http.Request, out any) bool { r.Body = http.MaxBytesReader(w, r.Body, 32768) defer r.Body.Close() decoder := json.NewDecoder(r.Body) decoder.DisallowUnknownFields() if err := decoder.Decode(out); err != nil { writeError(w, 400, errors.New("invalid course request")) return false } if decoder.Decode(new(any)) != io.EOF { writeError(w, 400, errors.New("trailing request content")) return false } return true } func (s *Server) adaptiveCatalog(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } user, err := s.store.GetUser(r.Context(), currentUserID(r)) if err != nil { adaptiveError(w, err) return } snap, err := s.course.Repo.Snapshot(r.Context(), user.ID, p.TargetLanguage, user.ExplanationLanguage()) if err != nil { adaptiveError(w, err) return } languages, err := s.store.ListLanguages(r.Context()) if err != nil { adaptiveError(w, err) return } available := []string{} for _, l := range languages { modules, err := s.course.Repo.Modules(r.Context(), l.Code) if err != nil { adaptiveError(w, err) return } if len(modules) == 7 { available = append(available, l.Code) } } exams, err := s.course.Repo.Exams(r.Context(), user.ID, p.TargetLanguage) if err != nil { adaptiveError(w, err) return } analysisJob, err := s.course.Repo.LatestAnalysisJob(r.Context(), user.ID, p.TargetLanguage) if err != nil { adaptiveError(w, err) return } if s.course.Mode == "bank" { snap.PreviousAnalysis = nil analysisJob = nil } inventory, err := s.course.Repo.BankInventory(r.Context(), user.ID, p.TargetLanguage) if err != nil { adaptiveError(w, err) return } instructionLanguages, err := s.course.Repo.InstructionLanguages(r.Context(), p.TargetLanguage) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, map[string]any{"instruction_language": user.ExplanationLanguage(), "instruction_languages": instructionLanguages, "exam_available": s.course.Mode != "bank" || user.ExplanationLanguage() == "de-DE", "task_mode": s.course.Mode, "grading_available": s.course.EvaluationAvailable(r.Context()), "bank": inventory, "analysis_job": analysisJob, "profile": p, "modules": snap.Modules, "progress": snap.Progress, "analysis": snap.PreviousAnalysis, "facts_version": snap.FactsVersion, "enabled_languages": available, "languages": languages, "exams": exams}) } func (s *Server) adaptiveNext(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } var input struct { RequestID string `json:"request_id"` Skill string `json:"skill"` } if !adaptiveJSON(w, r, &input) { return } if !courseRequestIDPattern.MatchString(input.RequestID) || !validCourseSkill(input.Skill) { writeError(w, 400, errors.New("invalid request ID or skill")) return } if _, err := s.course.Repo.Module(r.Context(), p.TargetLanguage, r.PathValue("id")); err != nil { adaptiveError(w, err) return } j, err := s.course.Repo.Enqueue(r.Context(), currentUserID(r), p.TargetLanguage, "next", r.PathValue("id"), input.Skill, "", input.RequestID) if err != nil { adaptiveError(w, err) return } writeJSON(w, 202, j) } func validCourseSkill(skill string) bool { if skill == "" { return true } for _, s := range domain.CourseSkills { if s == skill { return true } } return false } func (s *Server) adaptiveHistory(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } if _, err := s.course.Repo.Module(r.Context(), p.TargetLanguage, r.PathValue("id")); err != nil { adaptiveError(w, err) return } offset := 0 if value := r.URL.Query().Get("offset"); value != "" { n, err := strconv.Atoi(value) if err != nil || n < 0 { writeError(w, 400, errors.New("invalid history offset")) return } offset = n } tasks, err := s.course.Repo.History(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id"), offset) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, map[string]any{"tasks": tasks, "offset": offset, "has_more": len(tasks) == 25}) } func (s *Server) adaptiveJob(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } j, err := s.course.Repo.Job(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, j) } func (s *Server) adaptiveRetryJob(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } if s.course.Mode == "bank" { existing, err := s.course.Repo.Job(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } if existing.Kind == "evaluate" && !s.course.EvaluationAvailable(r.Context()) { writeError(w, 409, errors.New("KI-Bewertung derzeit nicht verfügbar. Die Antwort bleibt gespeichert.")) return } } j, err := s.course.Repo.RetryJob(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } writeJSON(w, 202, j) } func (s *Server) adaptiveTask(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } user := currentUserID(r) task, err := s.course.Repo.Task(r.Context(), user, p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } latest, err := s.course.Repo.LatestTaskAttempt(r.Context(), user, p.TargetLanguage, task.ID) if err != nil { adaptiveError(w, err) return } reveal := latest != nil && (latest.Status == "graded" || latest.Status == "ungraded") if task.ExamID != "" { exam, err := s.course.Repo.Exam(r.Context(), user, p.TargetLanguage, task.ExamID) if err != nil { adaptiveError(w, err) return } reveal = exam.Status == "completed" } if latest != nil { value, err := s.course.PublicAttempt(r.Context(), user, p.TargetLanguage, *latest) if err != nil { adaptiveError(w, err) return } latest = &value } writeJSON(w, 200, map[string]any{"task": task.Public(reveal), "attempt": latest}) } func (s *Server) adaptiveAttempt(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } var input struct { RequestID string `json:"request_id"` Answer string `json:"answer"` } if !adaptiveJSON(w, r, &input) { return } legacyResponse := input.RequestID == "" answer := strings.TrimSpace(input.Answer) if input.RequestID == "" { input.RequestID = newRequestID() } if !courseRequestIDPattern.MatchString(input.RequestID) || answer == "" || len([]rune(answer)) > 10000 { writeError(w, 400, errors.New("answer and request ID are required; maximum 10000 characters")) return } task, err := s.course.Repo.Task(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } if task.Kind == "repeat_sentence" || task.Kind == "free_speech" { writeError(w, 400, errors.New("this task requires an audio recording")) return } if task.Kind == "choice" { valid := false for _, option := range task.Options { if answer == option.ID || answer == option.Label { valid = true break } } if !valid { writeError(w, 400, errors.New("Bitte eine der angebotenen Antworten wählen.")) return } } attempt, job, err := s.course.Submit(r.Context(), currentUserID(r), p.TargetLanguage, task.ID, input.RequestID, answer, nil) if err != nil { adaptiveError(w, err) return } public, err := s.course.PublicAttempt(r.Context(), currentUserID(r), p.TargetLanguage, attempt) if err != nil { adaptiveError(w, err) return } status := 201 if job != nil { status = 202 } if legacyResponse && task.ExamID == "" && public.Evaluation != nil { solution := task.AnswerKey.ReferenceAnswer for _, option := range task.Options { if option.ID == task.AnswerKey.CorrectOptionID { solution = option.Label } } writeJSON(w, 201, domain.CourseAttemptResult{ID: public.ID, TaskID: task.ID, Correct: public.Evaluation.Verdict == "correct", Solution: solution, Explanation: public.Evaluation.Feedback, Transcript: task.AudioText}) return } writeJSON(w, status, map[string]any{"attempt": public, "job": job}) } func (s *Server) adaptiveGetAttempt(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } a, err := s.course.Repo.Attempt(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } a, err = s.course.PublicAttempt(r.Context(), currentUserID(r), p.TargetLanguage, a) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, a) } func (s *Server) adaptiveRetryAttempt(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } if s.course.Mode == "bank" && !s.course.EvaluationAvailable(r.Context()) { writeError(w, 409, errors.New("KI-Bewertung derzeit nicht verfügbar. Die Antwort bleibt gespeichert.")) return } j, err := s.course.Repo.RetryEvaluation(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } writeJSON(w, 202, j) } func (s *Server) adaptiveAudio(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } t, err := s.course.Repo.Task(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } text := t.AudioText if t.Kind == "repeat_sentence" { text = t.ReferenceText } if text == "" { writeError(w, 404, store.ErrNotFound) return } lang, err := s.store.GetLanguage(r.Context(), p.TargetLanguage) if err != nil { adaptiveError(w, err) return } if lang.AzureLocale == "" || lang.DefaultTTSVoice == "" { writeError(w, 503, errors.New("speech is not configured for this language")) return } audio, mime, err := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, text) if err != nil || len(audio) == 0 { writeError(w, 503, errors.New("Audio ist momentan nicht verfügbar.")) return } w.Header().Set("Content-Type", mime) w.Header().Set("Cache-Control", "private, no-store") w.WriteHeader(200) _, _ = w.Write(audio) } // Parse the actual PCM header and frame count. A file extension or claimed // MIME type alone cannot establish the sample rate or the 30-second limit. func validCourseWAV(audio []byte) bool { if len(audio) < 44 || string(audio[:4]) != "RIFF" || string(audio[8:12]) != "WAVE" { return false } validFormat := false dataSize := 0 for pos := 12; pos+8 <= len(audio); { size := int(binary.LittleEndian.Uint32(audio[pos+4 : pos+8])) start := pos + 8 if size < 0 || size > len(audio)-start { return false } switch string(audio[pos : pos+4]) { case "fmt ": if size < 16 { return false } validFormat = binary.LittleEndian.Uint16(audio[start:start+2]) == 1 && binary.LittleEndian.Uint16(audio[start+2:start+4]) == 1 && binary.LittleEndian.Uint32(audio[start+4:start+8]) == 16000 && binary.LittleEndian.Uint16(audio[start+14:start+16]) == 16 && binary.LittleEndian.Uint32(audio[start+8:start+12]) == 32000 && binary.LittleEndian.Uint16(audio[start+12:start+14]) == 2 case "data": dataSize += size } pos = start + size + size%2 } return validFormat && dataSize > 0 && dataSize <= 16000*2*30 && dataSize%2 == 0 } func (s *Server) adaptiveAudioAttempt(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } t, err := s.course.Repo.Task(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } if t.Kind != "repeat_sentence" && t.Kind != "free_speech" { writeError(w, 400, errors.New("this task does not accept audio")) return } r.Body = http.MaxBytesReader(w, r.Body, 2<<20) if err = r.ParseMultipartForm(2 << 20); err != nil { writeError(w, 400, errors.New("invalid audio upload")) return } if r.MultipartForm != nil { defer r.MultipartForm.RemoveAll() } requestID := r.FormValue("request_id") if !courseRequestIDPattern.MatchString(requestID) { writeError(w, 400, errors.New("request_id is required")) return } if old, err := s.course.Repo.AttemptByRequest(r.Context(), currentUserID(r), p.TargetLanguage, requestID); err == nil { if old.TaskID != t.ID { writeError(w, 400, errors.New("request belongs to another task")) return } a, err := s.course.PublicAttempt(r.Context(), currentUserID(r), p.TargetLanguage, old) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, map[string]any{"attempt": a}) return } else if !errors.Is(err, store.ErrNotFound) { adaptiveError(w, err) return } file, _, err := r.FormFile("audio") if err != nil { writeError(w, 400, errors.New("audio is required")) return } defer file.Close() audio, err := io.ReadAll(io.LimitReader(file, (1<<20)+1)) if err != nil || !validCourseWAV(audio) { writeError(w, 400, errors.New("Bitte eine WAV-Aufnahme mit 16 kHz, mono, maximal 30 Sekunden senden.")) return } lang, err := s.store.GetLanguage(r.Context(), p.TargetLanguage) if err != nil { adaptiveError(w, err) return } if lang.AzureLocale == "" { writeError(w, 503, errors.New("speech locale unavailable")) return } ctx, cancel := context.WithTimeout(r.Context(), 50*time.Second) defer cancel() transcript := t.ReferenceText if t.Kind == "free_speech" { transcriber, ok := s.speech.(interface { Transcribe(context.Context, []byte, string, string) (string, error) }) if !ok { writeError(w, 503, errors.New("free speech is unavailable")) return } transcript, err = transcriber.Transcribe(ctx, audio, "audio/wav", lang.AzureLocale) if err != nil { writeError(w, 503, errors.New("Die Aufnahme konnte nicht transkribiert werden. Bitte erneut senden.")) return } } var speech *domain.PronunciationResult if lang.SupportsPronunciationAssessment { result, err := s.speech.AssessPronunciation(ctx, services.PronunciationInput{Audio: audio, ContentType: "audio/wav", TargetText: transcript, Locale: lang.AzureLocale}) if err != nil { writeError(w, 503, errors.New("Die Sprachmessung ist fehlgeschlagen. Die Aufnahme kann erneut gesendet werden.")) return } if t.Kind == "free_speech" { result.Method = "unscripted" result.CompletenessScore = 0 result.RecognizedText = transcript } if result.Provider != "azure" { writeError(w, 503, errors.New("Für Kursaufnahmen ist eine echte Azure-Sprachmessung erforderlich.")) return } speech = &result } else if t.Kind == "repeat_sentence" { transcriber, ok := s.speech.(interface { Transcribe(context.Context, []byte, string, string) (string, error) }) if !ok { writeError(w, 503, errors.New("speech is unavailable")) return } transcript, err = transcriber.Transcribe(ctx, audio, "audio/wav", lang.AzureLocale) if err != nil { writeError(w, 503, errors.New("Die Aufnahme konnte nicht transkribiert werden.")) return } } answer := transcript if speech != nil && t.Kind == "repeat_sentence" { answer = speech.RecognizedText } if strings.TrimSpace(answer) == "" { writeError(w, 400, errors.New("no speech recognized")) return } a, job, err := s.course.Submit(r.Context(), currentUserID(r), p.TargetLanguage, t.ID, requestID, answer, speech) if err != nil { adaptiveError(w, err) return } a, err = s.course.PublicAttempt(r.Context(), currentUserID(r), p.TargetLanguage, a) if err != nil { adaptiveError(w, err) return } writeJSON(w, 202, map[string]any{"attempt": a, "job": job}) } func (s *Server) adaptiveNewExam(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } var input struct { RequestID string `json:"request_id"` } if !adaptiveJSON(w, r, &input) { return } if !courseRequestIDPattern.MatchString(input.RequestID) { writeError(w, 400, errors.New("request_id is required")) return } mods, err := s.course.Repo.Modules(r.Context(), p.TargetLanguage) if err != nil { adaptiveError(w, err) return } if len(mods) != 7 { writeError(w, 404, store.ErrNotFound) return } if s.course.Mode == "bank" { user, err := s.store.GetUser(r.Context(), currentUserID(r)) if err != nil { adaptiveError(w, err) return } if user.ExplanationLanguage() != "de-DE" { exists, err := s.course.Repo.HasExamRequest(r.Context(), user.ID, p.TargetLanguage, input.RequestID) if err != nil { adaptiveError(w, err) return } if !exists { adaptiveError(w, store.ErrCourseVariantUnavailable) return } } } exam, err := s.course.Repo.NewExam(r.Context(), currentUserID(r), p.TargetLanguage, input.RequestID) if err != nil { adaptiveError(w, err) return } job, err := s.course.Repo.Enqueue(r.Context(), currentUserID(r), p.TargetLanguage, "exam", mods[6].ID, "", exam.ID, "exam:"+exam.ID) if err != nil { adaptiveError(w, err) return } writeJSON(w, 202, map[string]any{"exam": exam, "job": job}) } func (s *Server) adaptiveExam(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } exam, err := s.course.Repo.Exam(r.Context(), currentUserID(r), p.TargetLanguage, r.PathValue("id")) if err != nil { adaptiveError(w, err) return } writeJSON(w, 200, exam) } // The compatibility endpoint retains its synchronous choice response. New // clients use jobs; old clients can still submit the displayed option label. func (s *Server) adaptiveLegacyNext(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } var input struct { RequestID string `json:"request_id"` } if !adaptiveJSON(w, r, &input) { return } if !courseRequestIDPattern.MatchString(input.RequestID) { writeError(w, 400, errors.New("invalid request_id")) return } module := r.PathValue("id") if _, err := s.course.Repo.Module(r.Context(), p.TargetLanguage, module); err != nil { adaptiveError(w, err) return } j, err := s.course.Repo.Enqueue(r.Context(), currentUserID(r), p.TargetLanguage, "legacy_next", module, "vocabulary", "", input.RequestID) if err != nil { adaptiveError(w, err) return } timer := time.NewTimer(25 * time.Second) defer timer.Stop() ticker := time.NewTicker(250 * time.Millisecond) defer ticker.Stop() for j.Status == "queued" || j.Status == "running" { select { case <-r.Context().Done(): return case <-timer.C: goto fallback case <-ticker.C: j, err = s.course.Repo.Job(r.Context(), currentUserID(r), p.TargetLanguage, j.ID) if err != nil { adaptiveError(w, err) return } } } if j.Status == "succeeded" && j.TaskID != "" { t, err := s.course.Repo.Task(r.Context(), currentUserID(r), p.TargetLanguage, j.TaskID) if err != nil { adaptiveError(w, err) return } writeLegacyAdaptiveTask(w, t) return } fallback: t, err := s.course.Repo.Reserve(r.Context(), currentUserID(r), p.TargetLanguage, module, "vocabulary") if err != nil { adaptiveError(w, err) return } writeLegacyAdaptiveTask(w, t) } func legacyAdaptiveTask(t domain.AdaptiveTask) domain.CourseTask { task := domain.CourseTask{ID: t.ID, ModuleID: t.ModuleID, Skill: t.Skill, Kind: t.Kind, Prompt: t.Prompt, Passage: t.Passage, Source: t.Source, Options: []string{}} for _, o := range t.Options { task.Options = append(task.Options, o.Label) } return task } func writeLegacyAdaptiveTask(w http.ResponseWriter, t domain.AdaptiveTask) { writeJSON(w, 200, domain.CoursePracticeResult{Task: legacyAdaptiveTask(t), Source: t.Source}) } // Preference changes affect future jobs only. Task snapshots keep their original // instructions, keys and evidence identity, including tasks in older exams. func (s *Server) adaptiveInstructionLanguage(w http.ResponseWriter, r *http.Request) { p, ok := s.adaptiveProfile(w, r) if !ok { return } var input struct { InstructionLanguage string `json:"instruction_language"` } if !adaptiveJSON(w, r, &input) { return } if err := s.course.Repo.SetInstructionLanguage(r.Context(), currentUserID(r), p.TargetLanguage, input.InstructionLanguage); err != nil { adaptiveError(w, err) return } writeJSON(w, 200, map[string]string{"instruction_language": input.InstructionLanguage}) }