API de verificação de visualizações do Velog (beta)

Contexto de desenvolvimento e ideia de implementação

• Eu queria saber o número de visualizações dos posts que escrevi no Velog, mas era incômodo ter que fazer login toda vez para conferir
• Eu até poderia fazer engenharia reversa da API interna de visualizações do Velog, mas isso provavelmente seria mais trabalhoso e teria baixa escalabilidade (ex.: alerta de visitantes)
• Lembrei que antigos serviços de e-mail coreanos ofereciam confirmação de leitura usando imagens em pixel
• O Velog oferece suporte à escrita de posts usando sintaxe Markdown
• O navegador não bloqueia chamadas simples de imagem mesmo em domínios cross-site
• Se você inserir uma imagem transparente de 1x1 pixel no post, o servidor pode registrar a chamada sempre que o post for visualizado
• A maioria dos posts dos usuários do Velog não recebe mais de 1.000 visitantes por dia. Para esse nível de tráfego, usar Workers KV já é suficiente
• Isso não se limita ao Velog: pode ser usado em qualquer plataforma que suporte inserção de imagens via sintaxe Markdown (e permita servir imagens de um domínio do usuário)

Como funciona

• Depois de atribuir um valor de identificação (slug) à imagem, em vez de usar um CDN, a resposta é fornecida por Workers programáveis; se esse valor de identificação for usado como Key prefix no KV para armazenar o histórico de chamadas, dá para obter page views de forma simples
• Se data, ip, userAgent e valor de identificação da imagem forem transformados em uma key usando uma função de Hash, é possível tratar o mínimo de visitas duplicadas
  • HASH: hash de 128 bits baseado em SHA-256, codificado em base64url (22 caracteres).
  • KEY: view:${slug}:${hash}.
  • VALUE: UserAgent, Date...
• O plano gratuito do Workers KV oferece 1.000 PUT e LIST por dia.
  • PUT: permite armazenar informações de contagem de visitantes para até 1.000 visitas por dia
  • LIST: permite fornecer informações de page view para mais de 1.000 consultas por dia
• As requisições para consultar page views usam o comando LIST; basta buscar usando o valor de identificação (slug) como prefix e então fazer uma contagem simples
  • Como a consulta de page views não exige tanta atualização em tempo real, se o valor de resposta for armazenado em cache de forma adequada, torna-se possível lidar com mais de 1.000 requisições por dia

Limitações

Como foi usado KV, um armazenamento simples, para permitir desenvolvimento rápido, existem as seguintes limitações.

• Eventual consistency: requisições PUT no Workers KV não são em tempo real. Se tempo real for realmente necessário, é preciso usar Durable Objects(DO).
• Dependência de LIST: a contagem baseada no comando LIST vai ficando mais lenta com o tempo, à medida que aumenta a quantidade de KEYs que precisam ser buscadas (assumindo que a página continue recebendo visualizações). É preciso considerar atualizar continuamente a estrutura de armazenamento com tarefas Cron, ou usar DO ou Analytics Engine.

Suporte planejado

Pretendo adicionar os seguintes recursos o mais rápido possível.

• Ordenação por data: usando Unix Time, da mesma forma que foi usado para ordenar comentários mais recentes em Criando uma API serverless de comentários para blog em 30 minutos, será possível fornecer uma lista ordenada com base nas sessões mais recentes
• Segurança da API: será suportada por meio da adição de middleware. A ideia é usar o header HTTP Authorization
• Rate Limit: se for um usuário popular do Velog, talvez apareçam usuários movidos por inveja e malícia enviando requisições maliciosas, então é necessário ter uma proteção. Provavelmente, como isso não se aplica a mim, vai ser o último item a ser adicionado...
• Busca: será suportada com a adição de API
  • Data: busca por data específica e por período. Será necessário alterar a estrutura da KEY
  • Sessão: busca por informações de atividade de uma sessão específica. Atualmente, as informações de sessão são válidas por um dia para cada post. É necessário revisar a política de privacidade
  • Navegador/OS: será fornecido com base em informações extraídas do UserAgent. Mesmo sem muita precisão, já permite uma visão geral
• API como serviço: a API será oferecida em formato de serviço para que qualquer pessoa possa usar com facilidade via verificação por e-mail + emissão de chave privada
  • Webhook: fornecerá requisições POST quando ocorrer um evento de page view. Isso permitirá notificações usando Slack, que os desenvolvedores adoram
  • E-mail: uma funcionalidade de alerta clássica, mas conveniente, para usuários que acham incômodo lidar com webhooks
  • Custom campaign: fornecerá um valor de identificação de imagem (slug) integrado a eventos configurados (ex.: atingir um determinado número de visualizações)

Adicional

• Para quem tiver interesse na estrutura interna de funcionamento, consulte Relato de desenvolvimento da API de verificação de visualizações do Velog, começando com um pixel 1x1.
• O método de instalação e deploy, a API Reference detalhada e o código completo podem ser conferidos no repositório Github.