DEV Community: João Abreu

Building a Waitlist with Automatic Promotion in Spring Boot (and Keeping the Queue Gap-Free)

João Abreu — Sun, 01 Nov 2026 15:15:51 +0000

🇺🇸 English version (🇧🇷 versão em português logo abaixo)

The problem: sessions with limited spots

I'm building a tutoring management system with Java, Spring Boot and PostgreSQL. Students can become tutors for a subject, and tutors open sessions with a limited number of spots.

That raised a real business question: what happens when a session is full? I didn't want to just return "Session is full". I wanted an optional waitlist:

if there's a free spot, the student is confirmed;
if the session is full and allows a waitlist, the student goes to the queue;
when a confirmed student cancels, the first in line is promoted automatically and gets notified;
the rest of the queue moves up, with no gaps (1, 2, 3... never 2, 3, 5).

Modeling the enrollment

Each enrollment has a status and an optional position in the queue:

CONFIRMED → has a spot, queuePosition is null
WAITLISTED → waiting, queuePosition is 1, 2, 3...
CANCELLED → left the session, queuePosition is null

In the database, I made sure an invalid position can never be saved:

CREATE TABLE enrollment (
    id             UUID PRIMARY KEY,
    status         enrollment_status NOT NULL,
    queue_position INT               CHECK (queue_position >= 1),
    session_id     UUID              NOT NULL REFERENCES session (id),
    student_id     UUID              NOT NULL REFERENCES users (id),
    created_at     TIMESTAMPTZ       NOT NULL DEFAULT NOW()
);

The repository only needs two Spring Data derived queries. No SQL written by hand:

long countBySessionAndStatus(Session session, EnrollmentStatus enrollmentStatus);

List<Enrollment> findBySessionAndStatusOrderByQueuePositionAsc(Session session, EnrollmentStatus enrollmentStatus);

Enrolling: confirmed or waitlisted?

After checking that the session exists, is active and the student isn't already enrolled, the enroll method decides where the student goes:

long confirmedCount = enrollmentRepository.countBySessionAndStatus(session, EnrollmentStatus.CONFIRMED);

if (confirmedCount < session.getSpots()) {
    Enrollment enrollment = new Enrollment(EnrollmentStatus.CONFIRMED, session, student);
    return enrollmentRepository.save(enrollment);
}

if (session.isAllowsWaitlist()) {
    long waitlistedCount = enrollmentRepository.countBySessionAndStatus(session, EnrollmentStatus.WAITLISTED);

    int queuePosition = (int) waitlistedCount + 1;

    Enrollment enrollment = new Enrollment(EnrollmentStatus.WAITLISTED, session, student);
    enrollment.setQueuePosition(queuePosition);

    return enrollmentRepository.save(enrollment);
}

throw new SessionFullException("Session is full");

If there's no spot and no waitlist, a SessionFullException is thrown, and my @RestControllerAdvice turns it into a 409 Conflict.

Cancelling: promoting the first in line

This is the most interesting part. When a student cancels, three things must happen together:

the enrollment becomes CANCELLED;
if that student had a confirmed spot, the first in the queue is promoted and notified;
the queue is renumbered.

@Transactional
public Enrollment cancelEnrollment(UUID enrollmentUuid, UUID userUuid) {
    // ... find the enrollment, check permission and status

    EnrollmentStatus previousStatus = enrollment.getStatus();

    enrollment.setStatus(EnrollmentStatus.CANCELLED);
    enrollment.setQueuePosition(null);

    List<Enrollment> waitlist = enrollmentRepository
            .findBySessionAndStatusOrderByQueuePositionAsc(enrollment.getSession(), EnrollmentStatus.WAITLISTED);

    if (previousStatus == EnrollmentStatus.CONFIRMED && !waitlist.isEmpty()) {
        Enrollment promoted = waitlist.get(0);
        promoted.setStatus(EnrollmentStatus.CONFIRMED);
        promoted.setQueuePosition(null);
        Notification notification = new Notification(NotificationEventType.SPOT_PROMOTED,
                "You have been promoted from the waitlist", promoted.getStudent());
        notificationRepository.save(notification);
    }

    // ... renumber the queue (next section)
}

Notice previousStatus: if the student who cancelled was only waiting, no spot was freed, so nobody gets promoted. The queue still has to be renumbered, though.

Renumbering the queue without gaps

After the promotion, the list still contains the promoted student (now CONFIRMED). So I only renumber whoever is still WAITLISTED:

int position = 1;

for (Enrollment waiting : waitlist) {
    if (waiting.getStatus() == EnrollmentStatus.WAITLISTED) {
        waiting.setQueuePosition(position);
        position++;
    }
}

enrollmentRepository.saveAll(waitlist);
return enrollmentRepository.save(enrollment);

The @Transactional is what makes this safe: cancelling, promoting, notifying and renumbering are all or nothing. If anything fails halfway, nothing is saved, and I never end up with a cancelled spot and nobody promoted.

Proving it with unit tests

I tested the service with JUnit 5 and Mockito. The main scenario: a queue with positions 1, 2 and 3, and a confirmed student cancels. Expected result: the 1st becomes CONFIRMED, the others become 1 and 2, and a notification goes to the right student.

Enrollment enrollmentTest = sessionService.cancelEnrollment(enrollmentUuid, student.getId());

Assertions.assertEquals(EnrollmentStatus.CANCELLED, enrollmentTest.getStatus());
Assertions.assertNull(enrollmentTest.getQueuePosition());

Assertions.assertEquals(EnrollmentStatus.CONFIRMED, firstWaiting.getStatus());
Assertions.assertNull(firstWaiting.getQueuePosition());
Assertions.assertEquals(1, secondWaiting.getQueuePosition());
Assertions.assertEquals(2, thirdWaiting.getQueuePosition());

ArgumentCaptor<Notification> notification = ArgumentCaptor.forClass(Notification.class);
verify(notificationRepository).save(notification.capture());

Assertions.assertEquals(NotificationEventType.SPOT_PROMOTED, notification.getValue().getEventType());
Assertions.assertEquals(promotedStudent, notification.getValue().getReceiver());

ArgumentCaptor was new to me: it lets you grab the object passed to the mock and check what was saved, not only that something was saved.

What I learned and next steps

Modeling the states (CONFIRMED, WAITLISTED, CANCELLED) first made the code much simpler.
Validating in two places (service + CHECK constraint in the database) protects data even if a bug slips through.
@Transactional matters most when one action changes several rows.
A next step: enroll checks the count and then saves. Two students enrolling at the exact same moment could both see the last spot free. I want to study locking (for example, a pessimistic lock on the session) to handle that.

The full code is on GitHub: jg-abreu/tutoring-management-system

Thanks for reading! Feedback is very welcome. 🙌

🇧🇷 Versão em português

Criando uma lista de espera com promoção automática no Spring Boot (sem buracos na fila)

O problema: sessões com vagas limitadas

Estou construindo um sistema de gestão de monitorias com Java, Spring Boot e PostgreSQL. Alunos podem virar monitores de uma disciplina, e os monitores abrem sessões com um número limitado de vagas.

Isso trouxe uma pergunta de negócio real: o que acontece quando a sessão lota? Eu não queria só responder "Session is full". Queria uma lista de espera opcional:

se tem vaga, o aluno fica confirmado;
se a sessão está cheia e aceita lista de espera, o aluno entra na fila;
quando um aluno confirmado cancela, o primeiro da fila é promovido automaticamente e recebe uma notificação;
o resto da fila anda, sem buracos (1, 2, 3... nunca 2, 3, 5).

Modelando a inscrição

Cada inscrição tem um status e uma posição opcional na fila:

CONFIRMED → tem vaga, queuePosition é null
WAITLISTED → esperando, queuePosition é 1, 2, 3...
CANCELLED → saiu da sessão, queuePosition é null

No banco, garanti que uma posição inválida nunca seja salva:

CREATE TABLE enrollment (
    id             UUID PRIMARY KEY,
    status         enrollment_status NOT NULL,
    queue_position INT               CHECK (queue_position >= 1),
    session_id     UUID              NOT NULL REFERENCES session (id),
    student_id     UUID              NOT NULL REFERENCES users (id),
    created_at     TIMESTAMPTZ       NOT NULL DEFAULT NOW()
);

O repositório só precisa de duas derived queries do Spring Data, sem escrever SQL na mão:

long countBySessionAndStatus(Session session, EnrollmentStatus enrollmentStatus);

List<Enrollment> findBySessionAndStatusOrderByQueuePositionAsc(Session session, EnrollmentStatus enrollmentStatus);

Inscrevendo: confirmado ou na fila?

Depois de verificar que a sessão existe, está ativa e o aluno ainda não está inscrito, o método enroll decide para onde o aluno vai:

long confirmedCount = enrollmentRepository.countBySessionAndStatus(session, EnrollmentStatus.CONFIRMED);

if (confirmedCount < session.getSpots()) {
    Enrollment enrollment = new Enrollment(EnrollmentStatus.CONFIRMED, session, student);
    return enrollmentRepository.save(enrollment);
}

if (session.isAllowsWaitlist()) {
    long waitlistedCount = enrollmentRepository.countBySessionAndStatus(session, EnrollmentStatus.WAITLISTED);

    int queuePosition = (int) waitlistedCount + 1;

    Enrollment enrollment = new Enrollment(EnrollmentStatus.WAITLISTED, session, student);
    enrollment.setQueuePosition(queuePosition);

    return enrollmentRepository.save(enrollment);
}

throw new SessionFullException("Session is full");

Se não tem vaga nem lista de espera, é lançada uma SessionFullException, que o meu @RestControllerAdvice transforma em 409 Conflict.

Cancelando: promovendo o primeiro da fila

Essa é a parte mais interessante. Quando um aluno cancela, três coisas precisam acontecer juntas:

a inscrição vira CANCELLED;
se esse aluno tinha vaga confirmada, o primeiro da fila é promovido e notificado;
a fila é renumerada.

@Transactional
public Enrollment cancelEnrollment(UUID enrollmentUuid, UUID userUuid) {
    // ... busca a inscrição, verifica permissão e status

    EnrollmentStatus previousStatus = enrollment.getStatus();

    enrollment.setStatus(EnrollmentStatus.CANCELLED);
    enrollment.setQueuePosition(null);

    List<Enrollment> waitlist = enrollmentRepository
            .findBySessionAndStatusOrderByQueuePositionAsc(enrollment.getSession(), EnrollmentStatus.WAITLISTED);

    if (previousStatus == EnrollmentStatus.CONFIRMED && !waitlist.isEmpty()) {
        Enrollment promoted = waitlist.get(0);
        promoted.setStatus(EnrollmentStatus.CONFIRMED);
        promoted.setQueuePosition(null);
        Notification notification = new Notification(NotificationEventType.SPOT_PROMOTED,
                "You have been promoted from the waitlist", promoted.getStudent());
        notificationRepository.save(notification);
    }

    // ... renumera a fila (próxima seção)
}

Repare no previousStatus: se quem cancelou estava só esperando, nenhuma vaga foi liberada, então ninguém é promovido. Mas a fila ainda precisa ser renumerada.

Renumerando a fila sem buracos

Depois da promoção, a lista ainda contém o aluno promovido (agora CONFIRMED). Por isso só renumero quem continua WAITLISTED:

int position = 1;

for (Enrollment waiting : waitlist) {
    if (waiting.getStatus() == EnrollmentStatus.WAITLISTED) {
        waiting.setQueuePosition(position);
        position++;
    }
}

enrollmentRepository.saveAll(waitlist);
return enrollmentRepository.save(enrollment);

O @Transactional é o que torna isso seguro: cancelar, promover, notificar e renumerar é tudo ou nada. Se algo falhar no meio, nada é salvo, e nunca fico com uma vaga cancelada sem ninguém promovido.

Provando com testes unitários

Testei o service com JUnit 5 e Mockito. O cenário principal: uma fila com posições 1, 2 e 3, e um aluno confirmado cancela. Resultado esperado: o 1º vira CONFIRMED, os outros viram 1 e 2, e uma notificação vai para o aluno certo.

Enrollment enrollmentTest = sessionService.cancelEnrollment(enrollmentUuid, student.getId());

Assertions.assertEquals(EnrollmentStatus.CANCELLED, enrollmentTest.getStatus());
Assertions.assertNull(enrollmentTest.getQueuePosition());

Assertions.assertEquals(EnrollmentStatus.CONFIRMED, firstWaiting.getStatus());
Assertions.assertNull(firstWaiting.getQueuePosition());
Assertions.assertEquals(1, secondWaiting.getQueuePosition());
Assertions.assertEquals(2, thirdWaiting.getQueuePosition());

ArgumentCaptor<Notification> notification = ArgumentCaptor.forClass(Notification.class);
verify(notificationRepository).save(notification.capture());

Assertions.assertEquals(NotificationEventType.SPOT_PROMOTED, notification.getValue().getEventType());
Assertions.assertEquals(promotedStudent, notification.getValue().getReceiver());

O ArgumentCaptor era novidade para mim: ele permite pegar o objeto passado para o mock e verificar o que foi salvo, e não só que algo foi salvo.

O que aprendi e próximos passos

Modelar os estados primeiro (CONFIRMED, WAITLISTED, CANCELLED) deixou o código muito mais simples.
Validar em dois lugares (service + constraint CHECK no banco) protege os dados mesmo se um bug passar.
O @Transactional faz mais diferença quando uma ação altera várias linhas.
Um próximo passo: o enroll conta e depois salva. Dois alunos se inscrevendo exatamente no mesmo momento poderiam ver a última vaga livre ao mesmo tempo. Quero estudar locking (por exemplo, um lock pessimista na sessão) para tratar isso.

O código completo está no GitHub: jg-abreu/tutoring-management-system

Obrigado por ler! Feedback é muito bem-vindo. 🙌

Why my GETs worked but every POST got a 403: a CORS bug behind nginx in Docker

João Abreu — Tue, 20 Oct 2026 18:03:49 +0000

I'm a CS student building a tutoring management system: a Spring Boot REST API, a React frontend and PostgreSQL. While preparing the v1.2 release, I added a Docker Compose setup so anyone could run the whole stack with one command.

It almost worked. The pages loaded, the lists showed up... and every time I clicked a button that changed something, the API answered:

403 Forbidden
Invalid CORS request

This post is about why that happened, why only some requests failed, and the one-line fix.

The setup

Three containers:

services:
  db:        # PostgreSQL
  api:       # Spring Boot, port 8080
  frontend:  # nginx serving the React build, exposed as localhost:3000

The frontend doesn't call the API directly. nginx proxies everything under /api/ to the api container, so from the browser's point of view the frontend and the API live on the same origin, http://localhost:3000:

location /api/ {
    proxy_pass http://api:8080/;
    proxy_set_header Host $host;
}

On the Spring side, I already had a CORS config for local development, when the frontend runs on Vite's dev server:

registry.addMapping("/**")
        .allowedOrigins("http://localhost:5173")
        .allowedMethods("GET", "POST", "PATCH");

Same origin through the proxy, so CORS shouldn't even matter here. Right?

The weird part: only POST and PATCH failed

Listing subjects and sessions (GET) worked fine. Suggesting a subject, joining a session or approving something (POST/PATCH) all returned 403.

That was the clue. Browsers send the Origin header on POST and PATCH requests even when they are same-origin, but not on same-origin GETs. Spring only runs its CORS checks when an Origin header is present. So the GETs never went through the CORS logic at all, and the others did.

How Spring decides whether a request is "cross-origin"

When a request has an Origin header, Spring compares it with the request's own scheme, host and port. Spring builds that from the Host header it receives. If they match, it's a same-origin request and CORS is skipped. If they don't, it's a CORS request and the origin must be in allowedOrigins.

Now look at what each side saw:

	Value
`Origin` sent by the browser	`http://localhost:3000`
`Host` forwarded by nginx with `$host`	`localhost` (no port)
What Spring thinks it is	`http://localhost` (port 80)

localhost:3000 ≠ localhost:80, so Spring treated a same-origin request as cross-origin. And since http://localhost:3000 wasn't in my allowed origins (only the Vite one was), it rejected it with Invalid CORS request.

The culprit was $host. In nginx, $host is the host name without the port. $http_host is the Host header exactly as the browser sent it, with the port.

The fix

One variable:

location /api/ {
    proxy_pass http://api:8080/;
    # $http_host keeps the port (localhost:3000), so Spring sees the same origin as the
    # browser and skips CORS; $host drops it and every POST/PATCH failed with 403.
    proxy_set_header Host $http_host;
}

Now Spring sees Host: localhost:3000, which matches Origin: http://localhost:3000, and the request is same-origin again. No CORS check, no 403.

Why I didn't just add localhost:3000 to allowedOrigins

That would also make the error go away, and it's the first answer you find online. But it hides the real problem: the requests are same-origin, the proxy was just lying to the backend about where they came from. Fixing the header keeps the CORS config meaningful (it only lists origins that are really different, like the Vite dev server) and avoids a whitelist that has to change every time the port changes.

What I took away from it

"Only some methods fail" is a strong hint. In this case it pointed straight at the Origin header.
A reverse proxy changes what the backend sees. Headers like Host decide how the app understands the request, so they're worth checking first.
Fix the cause, not the symptom. Widening CORS would have worked, but it would have been the wrong fix.

The project is open source if you want to see the full Docker setup: tutoring-management-system. The fix is in v1.2.

Have you ever been bitten by a proxy header? I'd like to hear how you debugged it.

🇧🇷 Versão em português

Por que meus GETs funcionavam, mas todo POST dava 403: um bug de CORS atrás do nginx no Docker

Sou estudante de Ciência da Computação e estou construindo um sistema de gestão de monitorias: uma API REST em Spring Boot, um frontend em React e PostgreSQL. Preparando a versão 1.2, criei um Docker Compose pra qualquer pessoa rodar o sistema inteiro com um único comando.

Quase funcionou. As páginas carregavam, as listas apareciam... e toda vez que eu clicava num botão que alterava alguma coisa, a API respondia:

403 Forbidden
Invalid CORS request

Este post explica por que isso aconteceu, por que só algumas requisições falhavam e a correção de uma linha.

O cenário

Três containers:

services:
  db:        # PostgreSQL
  api:       # Spring Boot, porta 8080
  frontend:  # nginx servindo o build do React, exposto em localhost:3000

O frontend não chama a API diretamente. O nginx repassa tudo que está em /api/ para o container api, então, do ponto de vista do navegador, frontend e API estão na mesma origem, http://localhost:3000:

location /api/ {
    proxy_pass http://api:8080/;
    proxy_set_header Host $host;
}

No Spring, eu já tinha uma configuração de CORS para o desenvolvimento local, quando o frontend roda no servidor do Vite:

registry.addMapping("/**")
        .allowedOrigins("http://localhost:5173")
        .allowedMethods("GET", "POST", "PATCH");

Mesma origem pelo proxy, então o CORS nem deveria importar aqui. Certo?

A parte estranha: só POST e PATCH falhavam

Listar matérias e sessões (GET) funcionava. Sugerir uma matéria, entrar numa sessão ou aprovar algo (POST/PATCH) devolvia 403.

Essa foi a pista. O navegador envia o cabeçalho Origin em requisições POST e PATCH mesmo quando são da mesma origem, mas não em GETs da mesma origem. E o Spring só roda as verificações de CORS quando existe um cabeçalho Origin. Ou seja, os GETs nem passavam pela lógica de CORS, e os outros passavam.

Como o Spring decide se uma requisição é "cross-origin"

Quando a requisição tem Origin, o Spring compara esse valor com o esquema, host e porta da própria requisição, que ele monta a partir do cabeçalho Host que recebe. Se baterem, é mesma origem e o CORS é ignorado. Se não, é uma requisição CORS e a origem precisa estar em allowedOrigins.

Veja o que cada lado enxergava:

	Valor
`Origin` enviado pelo navegador	`http://localhost:3000`
`Host` repassado pelo nginx com `$host`	`localhost` (sem porta)
O que o Spring acha que é	`http://localhost` (porta 80)

localhost:3000 ≠ localhost:80, então o Spring tratou uma requisição da mesma origem como cross-origin. E como http://localhost:3000 não estava nas origens permitidas (só a do Vite), ele rejeitou com Invalid CORS request.

O culpado era o $host. No nginx, $host é o nome do host sem a porta. Já $http_host é o cabeçalho Host exatamente como o navegador enviou, com a porta.

A correção

Uma variável:

location /api/ {
    proxy_pass http://api:8080/;
    proxy_set_header Host $http_host;
}

Agora o Spring recebe Host: localhost:3000, que bate com Origin: http://localhost:3000, e a requisição volta a ser da mesma origem. Sem verificação de CORS, sem 403.

Por que não adicionei localhost:3000 no allowedOrigins

Isso também faria o erro sumir, e é a primeira resposta que aparece na internet. Mas esconde o problema real: as requisições são da mesma origem, o proxy é que estava informando errado ao backend de onde elas vinham. Corrigir o cabeçalho mantém a configuração de CORS com sentido (ela só lista origens realmente diferentes, como o servidor do Vite) e evita uma lista que precisa mudar toda vez que a porta mudar.

O que eu levei disso

"Só alguns métodos falham" é uma pista forte. Nesse caso, apontou direto para o cabeçalho Origin.
Um proxy reverso muda o que o backend enxerga. Cabeçalhos como Host definem como a aplicação entende a requisição, então vale olhar para eles primeiro.
Corrija a causa, não o sintoma. Liberar mais origens no CORS funcionaria, mas seria a correção errada.

O projeto é open source, se quiser ver o Docker completo: tutoring-management-system. A correção está na v1.2.

Já foi pego por um cabeçalho de proxy? Conta como você depurou.