Cookies em FastAPI

Configurando Cookies

No FastAPI, a configuração de cookies no servidor pode ser feita usando o método set_cookie, que está disponível no objeto Response e em suas subclasses. Este método aceita os seguintes parâmetros:

• key: Nome ou identificador do cookie. É um parâmetro obrigatório.
• value: Valor do cookie. Por padrão, é uma string vazia.
• max_age: Tempo de vida do cookie em segundos. Pode ser um número ou None. Quando definido como None, o cookie terá validade apenas durante a sessão atual do navegador (comportamento padrão).
• expires: Data ou momento em que o cookie expira. Assim como max_age, pode ser um número ou None. O padrão é limitar o cookie à sessão atual do navegador.
• path: o caminho da URL no qual o cookie será válido. O valor padrão é /, que representa a raiz da aplicação.
• domain: Domínio ao qual o cookie se aplica. O padrão é None.
• secure: Indica se o cookie será enviado somente em conexões HTTPS. Quando configurado como True, o cookie será transmitido apenas em solicitações seguras. O padrão é False.
• httponly: Define se o cookie estará acessível a scripts JavaScript no cliente. Quando configurado como True, o cookie será inacessível ao JavaScript, protegendo-o contra ataques como XSS. O padrão é False.
• samesite: Controla o envio de cookies em solicitações cross-origin (entre domínios). O valor padrão é lax, que restringe o envio do cookie na maioria dos cenários cross-origin.

O exemplo a seguir demonstra como configurar um cookie chamado last_visit, que armazena a data e hora do último acesso ao site:

from fastapi import FastAPI, Response
from datetime import datetime

app = FastAPI()

@app.get("/")
def root(response: Response):
    now = datetime.now()  # Obtém a data e hora atuais
    response.set_cookie(key="last_visit", value=now.isoformat())
    return {"message": "Cookie configurado"}

Nesse caso, o cookie last_visit contém a data e a hora do último acesso do usuário. Esse valor pode ser visualizado nas ferramentas de desenvolvedor do navegador.

Também é possível configurar cookies criando um objeto Response explicitamente. Veja o exemplo:

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from datetime import datetime

app = FastAPI()

@app.get("/")
def root():
    now = datetime.now()  # Obtém a data e hora atuais
    response = JSONResponse(content={"message": "Cookie configurado"})
    response.set_cookie(key="last_visit", value=now.isoformat())
    return response

Aqui, criamos uma resposta JSON explícita e adicionamos o cookie last_visit diretamente ao objeto de resposta antes de retorná-lo.

Obtendo Cookies

Para acessar cookies no servidor, o FastAPI fornece o objeto Cookie, que pode ser utilizado para vincular valores de cookies aos parâmetros da função. Veja como acessar o cookie last_visit previamente configurado:

from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/")
def root(last_visit: str = Cookie()):
    return {"last visit": last_visit}

Nesse exemplo, o valor do cookie last_visit é extraído da solicitação e retornado na resposta.

Lidando com Cookies Opcionais

Se o cookie for obrigatório e não estiver presente na solicitação, o FastAPI lançará uma exceção. Para evitar isso, você pode definir um valor padrão, como None, para lidar com situações onde o cookie pode estar ausente:

from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/")
def root(last_visit: str | None = Cookie(default=None)):
    if last_visit is None:
        return {"message": "Este é o seu primeiro acesso ao site"}
    else:
        return {"message": f"Seu último acesso foi em: {last_visit}"}

Nesse caso, se o cookie last_visit não estiver presente na solicitação, o servidor retornará uma mensagem indicando que é o primeiro acesso do usuário. Caso contrário, será retornada a data e hora do último acesso.

Documentação oficial:

• Cookies de Resposta - FastAPI