Skip to content

6. Escopos de dados

Uma aplicação web atende muitos usuários ao mesmo tempo, e cada usuário faz inúmeras requisições. Os dados podem, portanto, ser compartilhados em vários níveis, conhecidos como seu escopo:

  • escopo de aplicação: os dados são compartilhados por todos os usuários durante toda a vida útil do servidor (a lista de médicos, por exemplo);
  • escopo de requisição: os dados existem apenas durante uma única requisição (o modelo de uma view, o usuário logado conforme identificado para aquela requisição);
  • escopo de cliente: os dados são específicos de um usuário e devem persistir de uma requisição para a seguinte (o idioma selecionado, o usuário logado).

As aplicações web usam há muito tempo uma sessão mantida no servidor para esse último escopo: uma memória específica de cada navegador, identificada por um cookie de identificação ([JSESSIONID] em [Java], [PHPSESSID] em [PHP]). A sessão do [Flask] é diferente: como vimos no Exemplo 20, ela é armazenada em um cookie assinado no lado do cliente. O servidor não armazena nada entre duas requisições de um mesmo usuário: diz-se que ele é stateless (sem estado). Isso torna possível, por exemplo, executar vários servidores idênticos atrás de um balanceador de carga: qualquer um deles pode tratar qualquer requisição. A contrapartida é que um cookie está sob o controle do usuário; ele pode lê-lo e tentar modificá-lo. Por isso, apenas dados não sensíveis são armazenados ali e — se os dados precisam ser confiáveis — eles são assinados pelo servidor, que então detecta qualquer modificação: é o caso da sessão do [Flask] e do token de autenticação (veja o capítulo sobre autenticação).

No [Flask], cada escopo tem seu próprio contêiner:

Escopo
Suporte
Duração
aplicação
Um objeto criado na inicialização, armazenado em [app.extensions] e recuperado por [current_app] (exemplo 06)
Toda a vida útil do servidor, compartilhado por todas as requisições
Requisição
O objeto [g] e o próprio objeto [request] (exemplo 16)
o processamento de uma requisição
sessão
o objeto [session], um dicionário armazenado em um cookie assinado
até o navegador ser fechado (por padrão)
cliente
um cookie padrão definido por [set_cookie] (exemplo 22)
a duração definida por [max_age]

Os objetos [current_app], [g], [request] e [session] são importados do pacote [flask]. Eles são proxies (exemplo 05): durante uma requisição, cada um identifica o objeto dessa requisição (ou da aplicação que a processa).

6.1. Exemplo 23: Escopos

1
2
3
4
5
6
7
8
9
23-scopes/
├── app.py
├── controllers/
│   └── scopes.py
├── services/
│   └── counter.py
└── templates/
    └── scopes/
        └── scopes.html

6.1.1. Os objetos: services/counter.py

# services/counter.py: um contador compartilhado, e as informações de uma requisição
from itertools import count
from threading import Lock


# escopo de APLICAÇÃO: uma única instância (veja app.py)
class CounterService:

    def __init__(self):
        self._total = 0
        # várias requisições podem ser executadas AO MESMO TEMPO: o lock garante
        # que dois incrementos simultâneos não se percam
        self._lock = Lock()

    def increment(self) -> int:
        with self._lock:
            self._total += 1
            return self._total


# escopo de REQUISIÇÃO: uma instância por requisição (veja app.py, função start)
class RequestInfo:

    # um contador compartilhado por todas as instâncias (atributo de CLASSE);
    # next(...) é atômico: duas threads nunca obtêm o mesmo número
    _instances = count(1)

    def __init__(self, start: str):
        self.number = next(RequestInfo._instances)
        self.start = start
  • Linhas 7–18: um contador de visitas, com escopo de aplicação: um único objeto, compartilhado por todas as requisições. Como na lista de tarefas do Exemplo 20, um lock protege o incremento: a instrução [self._total += 1] não é atômica (ela lê o valor, incrementa e depois grava), e duas threads que a executem simultaneamente poderiam ler o mesmo valor — resultando na perda de uma visita;
  • linhas 22–30: informações de escopo de requisição: um objeto por requisição, contendo um número e a hora da requisição. O número vem de um contador compartilhado por todas as instâncias: [count(1)], do módulo padrão [itertools], é um iterador que produz 1, 2, 3... a cada vez que [next] é chamado. Trata-se de um atributo de classe (declarado no nível da classe, não no construtor): ele é compartilhado por todas as instâncias.

6.1.2. A configuração: app.py

# app.py: a aplicação do exemplo 23
from datetime import datetime
from pathlib import Path

from flask import Blueprint, Flask, g

from controllers.scopes import scopes
from services.counter import CounterService, RequestInfo

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # a chave que assina o cookie de sessão (escopo de SESSÃO)
    app.config["SECRET_KEY"] = "a-secret-key-for-example-23"
    # escopo de APLICAÇÃO: um único objeto, criado na inicialização, compartilhado por TODAS
    # as requisições de TODOS os usuários
    app.extensions["counter"] = CounterService()
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(scopes)

    # escopo de REQUISIÇÃO: o objeto g nasce e morre a cada requisição. Esta
    # função, executada ANTES da ação, guarda nele um objeto que a ação e a
    # view encontrarão de novo durante ESTA requisição
    @app.before_request
    def start():
        g.info = RequestInfo(datetime.now().strftime("%H:%M:%S.%f")[:-3])

    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • linha 18: a chave que assina o cookie de sessão;
  • linha 21: o objeto de escopo de aplicação;
  • linhas 29–31: antes de cada requisição, um objeto [RequestInfo] é armazenado em [g]. A ação e a view o recuperarão, mas somente durante essa requisição. [strftime("%H:%M:%S.%f")] formata a hora com seus microssegundos ([%f], seis dígitos); [[:-3]] remove os três últimos caracteres da string, deixando os milissegundos.

6.1.3. O controller: controllers/scopes.py

# controllers/scopes.py: os quatro escopos de dados
from flask import Blueprint, current_app, g, make_response, render_template, request, session

scopes = Blueprint("scopes", __name__)


@scopes.get("/")
def display():
    # APLICAÇÃO: o contador compartilhado
    total = current_app.extensions["counter"].increment()
    # SESSÃO: um dicionário específico deste navegador, que o Flask guarda em um
    # cookie ASSINADO (session); dura até o navegador ser fechado
    session["visits"] = session.get("visits", 0) + 1
    # CLIENTE: um dado mantido pelo NAVEGADOR em um cookie comum,
    # enviado de volta ao servidor a cada requisição
    my_visits = to_integer(request.cookies.get("myVisits")) + 1
    response = make_response(render_template(
        "scopes/scopes.html", total=total, instance=g.info.number,
        session_visits=session["visits"], my_visits=my_visits))
    response.set_cookie("myVisits", str(my_visits), httponly=True, samesite="Lax")
    return response


# "41" -> 41; None ou "abc" -> 0
def to_integer(text: str | None) -> int:
    try:
        return int(text)
    except (TypeError, ValueError):
        return 0
  • linha 10: o escopo de aplicação. [current_app] refere-se à aplicação que processa a requisição atual;
  • linha 13: o escopo de sessão. [session] é usado como um dicionário: [session.get("visits", 0)] retorna o valor da chave, ou 0 se ela estiver ausente. Quando a ação modifica a sessão, o [Flask] envia, junto com a resposta, um novo cookie, [session], que contém o dicionário assinado;
  • linha 16: o escopo de cliente, com um cookie comum, [myVisits], lido de [request.cookies]. Seu valor é uma string fornecida pelo navegador e pode, portanto, estar ausente ou ser inválido; a função [to_integer] retorna 0 nos dois casos;
  • Linhas 17–20: para definir um cookie, é preciso o objeto de resposta: [make_response] o constrói a partir da página gerada pela view (exemplo 05), e então [set_cookie] adiciona a ele o cabeçalho [Set-Cookie]. Sem [max_age], o cookie dura até o navegador ser fechado (é um cookie “de sessão”, conforme definido pelos navegadores);
  • linha 18: o escopo de requisição: o objeto armazenado em [g] pela função [start].

6.1.4. A view: templates/scopes/scopes.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Scopes</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
</head>
<body>
  <div class="container py-3">
    <h1 class="h3">The scopes of data</h1>
    {# g e session são acessíveis nas views, durante a MESMA requisição #}
    <ul>
      <li>application: {{ total }} visit(s) to the site, all browsers combined</li>
      <li>request: object no. {{ instance }} (no. {{ g.info.number }} in the view),
        request received at {{ g.info.start }}</li>
      <li>session: {{ session_visits }} visit(s) from this browser ({{ session["visits"] }} in the view)</li>
      <li>client: {{ my_visits }} visit(s) from this browser</li>
    </ul>
  </div>
</body>
</html>

Os objetos [g] e [session] também são acessíveis nas views. A view exibe os valores recebidos da ação e, entre parênteses, os mesmos valores lidos diretamente de [g] e [session]: durante a mesma requisição, a ação e a view enxergam os mesmos objetos.

6.1.5. Execução

Após duas visitas em um navegador:

Image

Vamos acompanhar as requisições usando o [curl], que age como um primeiro navegador, armazenando seus cookies no arquivo [a.txt]:

curl -i -c a.txt -b a.txt http://localhost:5000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 581
Set-Cookie: myVisits=1; HttpOnly; Path=/; SameSite=Lax
Set-Cookie: session=eyJ2aXNpdHMiOjF9.arfKwA.YK-2GACLdbCJ_NXM5dYJYlqEF-4; HttpOnly; Path=/
...
      <li>application: 1 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 2 (no. 2 in the view),
        request received at 15:38:08.779</li>
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1 visit(s) from this browser</li>
...

A resposta define dois cookies. O primeiro, [myVisits], contém o valor em texto simples. O segundo, [session], contém o dicionário da sessão: a parte anterior ao primeiro ponto é o JSON [{"visits":1}], codificado em Base64 (não comprimido, como no Exemplo 20, por ser curto); seguido da data e da assinatura.

O objeto de escopo de requisição tem o número 2, embora esta seja a primeira visita à página: isso ocorre porque a função [start] é executada antes de toda requisição recebida pela aplicação, inclusive as requisições para as quais não existe ação (neste caso, uma requisição a uma URL inexistente, feita pouco antes) e as requisições de arquivos estáticos. No navegador, cada página dispara, assim, uma segunda requisição, a da folha de estilos do [Bootstrap]: daí os números ímpares na captura de tela. Uma segunda visita, com os mesmos cookies:

curl -i -c a.txt -b a.txt http://localhost:5000/
1
2
3
4
5
6
7
8
Set-Cookie: myVisits=2; HttpOnly; Path=/; SameSite=Lax
Set-Cookie: session=eyJ2aXNpdHMiOjJ9.arfKwA.l68wWEMYpKTfN3xPp_lysXPExO8; HttpOnly; Path=/
...
      <li>application: 2 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 3 (no. 3 in the view),
        request received at 15:38:08.799</li>
      <li>session: 2 visit(s) from this browser (2 in the view)</li>
      <li>client: 2 visit(s) from this browser</li>

Um segundo “navegador”, com seu próprio arquivo de cookies, inicialmente vazio:

curl -c b.txt -b b.txt http://localhost:5000/
1
2
3
4
5
      <li>application: 3 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 4 (no. 4 in the view),
        request received at 15:38:08.813</li>
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1 visit(s) from this browser</li>

O contador da aplicação continuou a contar; a sessão e o cookie do segundo navegador recomeçam em 1. Por fim, um usuário mal-intencionado forja seus próprios cookies: 1.000 visitas em [myVisits], e uma sessão que pretende conter [{"visits":999}] (codificado em Base64 como [eyJ2aXNpdHMiOjk5OX0]), com a assinatura de outra sessão:

curl -b "myVisits=1000;session=eyJ2aXNpdHMiOjk5OX0.arfKwA.YK-2GACLdbCJ_NXM5dYJYlqEF-4" http://localhost:5000/
1
2
3
4
      <li>application: 4 visit(s) to the site, all browsers combined</li>
      ...
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1001 visit(s) from this browser</li>

O cookie comum foi aceito como está: 1.001 visitas. A sessão forjada, porém, foi rejeitada: sua assinatura não corresponde ao conteúdo, e o [Flask] a ignorou, como se estivesse ausente. Essa é a diferença essencial entre um cookie comum e um cookie assinado. Guardemos a regra: os dados vindos do cliente só são confiáveis se forem assinados pelo servidor; e, mesmo assinados, continuam legíveis: não colocamos nada secreto neles.