AlexandreHTRB's blog

Tabela periódica da computação

2026-06-23T00:00:00Z

Alguns dias atrás, comecei a pensar nas diferentes extensões de arquivos das linguagens de programação e percebi que elas se parecem com símbolos de elementos químicos. Aí pensei: "daria para fazer uma tabela periódica da computação".

A melhor tabela periódica em HTML que encontrei na internet foi a do Adrian Roselli. Ela é responsiva, funciona na vertical e horizontal, cobre todas as necessidades de acessibilidade, tem suporte a modo escuro, funciona offline e dá até para imprimir!

Procurei fazer uma tabela colocando o que considero de importante da computação como um todo e num sentido mais geral. Acabou sem espaço para coisas como padrões de arquitetura e design. Talvez para isso seja melhor uma tabela periódica de software, ao invés de uma da computação.

Clique aqui para acessar a tabela.

Fazendo um calendário de feriados com programação funcional

2026-01-06T00:00:00Z

Um dos meus projetos pessoais é o site Feriados do Brasil, que é um calendário com os feriados nacionais, estaduais e municipais de várias cidades do país. Enquanto eu desenvolvia esse projeto, encontrei um caso de uso interessante para aplicar programação funcional e resolvi compartilhar neste artigo, mostrando como ela pode fornecer soluções diferentes e elegantes para nossos desafios.

Feriados fixos e móveis

Existem dois tipos de feriados: os de datas fixas, que caem sempre em um mesmo dia de um mesmo mês, e os de datas móveis, cuja data varia de acordo com o ano. Os feriados móveis mais conhecidos são a Paixão de Cristo, o Carnaval e Corpus Christi.

Apesar de menos comuns, existem muitos feriados móveis, cada um com sua regra determinadora. A tabela abaixo mostra alguns deles.

Feriado móvel	Data
Paixão de Cristo	calculada via fórmula matemática
Terça-feira de Carnaval*	47 dias antes da Páscoa
Corpus Christi	60 dias depois da Páscoa
Pentecostes	50 dias após a Páscoa
Sagrado Coração de Jesus	8 dias após Corpus Christi
Dia do Comércio no Rio de Janeiro	Terceira segunda-feira de outubro
Feriados estaduais do Acre**	Se caírem entre terça-feira e quinta-feira, são deslocados para a sexta-feira seguinte
Feriados estaduais de Santa Catarina	Se caírem em dia útil, são deslocados para o domingo seguinte

* Carnaval não é um feriado oficial, apesar de ser celebrado em quase todo o país.
** Exceto para o Aniversário do Estado, em 15 de junho.

A questão é: como podemos armazenar os feriados em uma base de dados, considerando que alguns são fixos e outros são móveis? Mais ainda, os de datas móveis têm regras particulares para calcular as datas?

Solução via programação funcional

No projeto em questão, a listagem e cálculo de feriados são feitos inteiramente no frontend em JavaScript. Basicamente, os feriados de um município correspondem à união dos feriados nacionais, estaduais e municipais. No código, cada um desses conjuntos é representado por um array de funções.

const feriadosNacionais = [
  ff(JANEIRO, 1, "Ano Novo"),
  fm(calcularTercaFeiraDeCarnaval, "Carnaval"),
  fm(calcularSextaFeiraSanta, "Paixão de Cristo"),
  ff(ABRIL, 21, "Tiradentes"),
  ff(MAIO, 1, "Dia do Trabalho"),
  ff(SETEMBRO, 7, "Independência do Brasil"),
  ff(OUTUBRO, 12, "Dia de Nossa Senhora Aparecida"),
  ff(OUTUBRO, 28, "Dia do Servidor Público (ponto facultativo)"),
  ff(NOVEMBRO, 2, "Finados"),
  ff(NOVEMBRO, 15, "Proclamação da República"),
  ff(NOVEMBRO, 20, "Dia da Consciência Negra"),
  ff(DEZEMBRO, 25, "Natal")
];

ff e fm representam respectivamente feriado fixo e feriado móvel. Essas funções recebem o dia e mês ou então uma função para calcular a data, além da descrição do feriado. O retorno delas é outra função, que recebe como argumento o ano numérico e por sua vez retorna um objeto feriado, com a descrição e a data exata (JavaScript Date).

// feriado fixo
function ff(mes, dia, desc) {
  return function (ano) {
    return { data: new Date(ano, mes, dia), descricao: desc };
  }
}

// feriado móvel
function fm(funcCalcDia, desc) {
  return function (ano) {
    return { data: funcCalcDia(ano), descricao: desc };
  }
}

Aqui usamos dois conceitos da programação funcional: higher-order functions e currying.

Higher-order functions são funções que recebem funções como parâmetro de entrada ou então que retornam funções como valores de saída (ou até as duas coisas ao mesmo tempo). fm() recebe funcCalcDia como argumento; esta por sua vez receberá um ano numérico e devolverá um objeto Date. Tanto fm() como ff() retornam funções.

Currying é uma estratégia de aninhamento de funções em cascata. No caso, ff e fm aninham as funções internas function (ano) {...}. Confira em mais detalhes este outro artigo sobre currying.

Para obter os feriados de um conjunto, basta iterar por cada função passando o ano como argumento:

let ano = 2026;
let feriados = feriadosNacionais.map((func) => func(ano));

// retorno:
[
  { data: new Date(2026, 1, 1), descricao: "Ano Novo" },
  { data: new Date(2026, 2, 17), descricao: "Carnaval" },
  { data: new Date(2026, 4, 3), descricao: "Paixão de Cristo" },
  // ...
]

O código em questão usado para o site é público e está disponível no GitHub.

Leituras interessantes

Excel como frontend

2025-09-29T00:00:00Z

As finanças pessoais e das empresas. Relatórios governamentais e gerenciais. Extratos de operações. Inventários. Projeções. Simulações. Listas de pessoas. 90% do PIB global. O que todas essas coisas têm em comum?

Todas elas passam pelo Excel.

Nos projetos em que trabalhei, uma das funcionalidades mais pedidas pelos clientes é exportar dados para o Excel, principalmente em setores de back-office, para que os analistas possam encontrar informações, produzir relatórios e calcular somas com maior facilidade. Não só back-office — profissionais de campo, atendentes e vendedores também usam essa ferramenta.

Alguns exemplos da vida real:

Relatórios internos de transações de indivíduos;
Relatórios de vendas agrupadas por parceiro de negócio;
Um vendedor que precisa ver a lista de ofertas disponíveis para os clientes;
Um economista que precisa das taxas de inflação dos últimos meses;
Uma analista de RH que quer ver as horas trabalhadas dos funcionários;
Um analista de investimento que necessita do histórico de valores de um ativo.

O Excel é uma ótima ferramenta para visualizar dados e é muito intuitiva, facilmente usada por qualquer pessoa.

Tendo em vista que ele muitas vezes é o formato final dos dados, surge a questão: ao invés de ter uma aplicação web, com backend e frontend, hospedagem, servidores e etc., não poderíamos fazer tudo direto pelo Excel? Seria mais fácil, não? Neste artigo, vamos explorar essa idéia.

Conectando com fontes de dados externas

O Excel pode se conectar a fontes de dados externas e baixar dados delas. Existem várias integrações disponíveis, tais como:

XMLs provenientes da internet
Arquivos XML, CSV, TXT e XLSX
Arquivos posicionais
Bancos de dados, como SQL Server, PostgreSQL, MySQL
Azure Blob Storage
Endpoints HTTP
E diversas outras.

Por exemplo, vamos criar um arquivo XML local com o seguinte conteúdo:

<ipcas_anuais>
<ipca><ano>2014</ano><valor>6,41%</valor></ipca>
<ipca><ano>2015</ano><valor>10,67%</valor></ipca>
<ipca><ano>2016</ano><valor>6,29%</valor></ipca>
<ipca><ano>2017</ano><valor>2,95%</valor></ipca>
<ipca><ano>2018</ano><valor>3,75%</valor></ipca>
<ipca><ano>2019</ano><valor>4,31%</valor></ipca>
<ipca><ano>2020</ano><valor>4,52%</valor></ipca>
<ipca><ano>2021</ano><valor>10,06%</valor></ipca>
<ipca><ano>2022</ano><valor>5,78%</valor></ipca>
<ipca><ano>2023</ano><valor>4,62%</valor></ipca>
<ipca><ano>2024</ano><valor>4,83%</valor></ipca>
</ipcas_anuais>

No Excel, vamos na aba Dados, depois clicar em Nova Consulta > Do Arquivo > Do XML, e então selecionar nosso arquivo.

Após a importação, o resultado será como abaixo:

Sempre que quiser sincronizar os dados, basta ir na aba Consulta e clicar em Atualizar, e a tabela será atualizada com os dados remotos.

Vantagens

Fazer o Excel puxar dados remotos tem grandes vantagens.

Uma delas é que não precisamos gastar esforço, tempo e infraestrutura construindo um site para disponibilizar esses dados; basta prover uma planilha e a fonte de dados.

Até mesmo a segurança de acesso às informações já está resolvida:

Se a fonte de dados for um arquivo remoto, basta controlar as permissões de acesso a esse arquivo.
Se a fonte de dados for um banco de dados ou endpoint HTTP, pode-se passar uma credencial com permissões apenas para consultas autorizadas.
Autenticação Windows é uma opção para os casos acima.

Outra vantagem é que uma vez baixados, os dados ficam disponíveis para uso mesmo sem conexão com a Internet.

Por fim, ter planilhas individuais confere aos usuários grande liberdade de trabalho, pois eles podem customizar, fazer rascunhos e experimentos nelas.

Operações de escrita

Podemos usar o Excel para inserir, excluir e modificar dados remotos? Sim. O caminho para se fazer isso são os UserForms e as macros.

Os UserForms são janelas e formulários customizáveis para que o usuário insira informações. Já as macros são o código por trás, que valida entradas e é responsável por se conectar a servidores e bancos de dados.

Exemplo de userform no Excel.

Deve-se ter em mente que sempre que for necessária uma mudança nessas integrações de escrita, os usuários terão de baixar versões atualizadas da planilha.

Recomendo os seguintes tutoriais de userforms: um do Excel Easy e outro da Wise Owl Training.

Conclusão

Para serviços internos de uma empresa, ou que usem muita matemática e dados em tabela, o Excel pode sim ser uma ótima alternativa.

Quando descobri que o Excel podia se conectar a fontes externas de dados, pensei "como que eu não sabia disso até hoje?". É muito mais prático. Por ser um software que não é usado diariamente pelos profissionais de TI, ele acaba não sendo conhecido em profundidade por nós, e às vezes, funcionalidades interessantes como essas passam despercebidas.

O que é currying?

2025-09-04T00:00:00Z

Currying é uma técnica para criar funções que compartilham uma mesma lógica. Nela, funções são aninhadas dentro de outras, cada uma sendo responsável por um parâmetro da lógica total.

Exemplo em JavaScript:

// função curryficada
function multiplicarESomar(a) {
  return function(b) {
    return function(x) {
      return a*x + b;
    }
  }
}

const f = multiplicarESomar(2)(1);
// f(x) = 2x + 1

console.log(f(4)); // 9

const g = multiplicarESomar(3);
// g(x) = 3x + b
// b não especificado ainda

console.log(g(2)(1)); // 5, b = 2

Com currying, subfunções podem aplicar argumentos fixos a uma função-mãe e herdar a declaração dos parâmetros restantes.

Uma forma de imaginar funções curryficadas é como se fossem bonecas russas (matryoshkas): uma dentro de outra, dentro de outra.

Fonte da imagem: AliExpress.

Essa técnica vem da programação funcional e é muito útil para cálculos e matemática.

Outro exemplo, em F#:

let volumePiramide(formulaAreaBase)(c)(l)(a) = 
  a * (formulaAreaBase(c)(l))/3.0

let areaRetangulo(c)(l) = c * l

let areaTriangulo(c)(l) = (c * l)/2.0

let areaCirculo(_)(r) = Math.PI * r**2.0

let volumePiramideBaseRetangular =
  volumePiramide(areaRetangulo)

let volumePiramideBaseTriangular =
  volumePiramide(areaTriangulo)

let volumeCone =
  volumePiramide(areaCirculo)(0)

// usos
let v1 = volumePiramideBaseRetangular(7.0)(4.0)(11.0)
let vc = volumeCone(9.0)(12.0) // raio 9, altura 12

Quanto menos um parâmetro varia entre as subfunções, mais à esquerda ele deve ficar na declaração curryficada.

Contêineres deveriam ser responsabilidade do sistema operacional

2025-06-10T00:00:00Z

Não antes de 2018, pouco a pouco, nos dias de trabalho na empresa, meus colegas começaram a falar sobre Docker, uma tecnologia que preparava ambientes para rodar os programas nos servidores. Menos de dois anos depois, Docker tinha se tornado a regra e aplicações novas vinham com Dockerfile e arquivos YAML para Kubernetes.

Apesar de entender a finalidade de uso dos contêineres, parte de mim dizia que eram uma solução desnecessariamente pesada e que os problemas solucionados deveriam ser tratados pelos sistemas operacionais. Minha opinião permanece.

Neste artigo, abordarei os problemas resolvidos pelos contêineres, alternativas e uma proposta para ser implementada por sistemas operacionais.

Começando pelo fim

Afinal de contas, por que usamos contêineres? A maioria absoluta das respostas é: "Porque preciso rodar minha aplicação na nuvem".

O Docker resolveu dois problemas: a preparação do ambiente e a segurança de execução.

A preparação do ambiente se dá porque as imagens dos contêineres vêm com o necessário para a execução do programa, que geralmente são o runtime da aplicação e pacotes relacionados. Isso pode ser complexo principalmente em ambientes Linux, pois há toda uma árvore de dependências que é sensível a mudanças e atualizações. Ter uma árvore de dependências rígida e reproduzível garante estabilidade, evitando que a aplicação pare de funcionar corretamente por incompatibilidade com alguma nova versão de um pacote.

A segurança de execução decorre de o contêiner ser um processo com mapeamento de rede e volume de arquivos isolados, sem risco de invadir e infectar arquivos da máquina principal.

Preparação de ambiente, sem contêineres

Existem várias formas de se preparar um ambiente sem recorrer a contêineres.

Uma é realmente instalar as dependências necessárias na máquina.

Outra é compilação autocontida (self-contained deployment), em que o executável carrega consigo o runtime da linguagem e todas suas dependências. Assim, a máquina não precisa ter ele instalado.

Algumas linguagens oferecem compilação para código de máquina, chamada de AOT (ahead-of-time compilation), que faz com que o runtime não seja necessário e também reduz o número de dependências externas, além de oferecer maior performance e menor consumo de memória aos programas.

A base de uma imagem Docker de sistema operacional é a user space, que é o sistema operacional, menos sua kernel. São programas essenciais, bibliotecas, serviços em background e outros arquivos.

Carregar uma user space de sistema operacional para cada contêiner desperdiça memória RAM e disco rígido. A imagem Docker do Ubuntu, por exemplo, ocupa 188MB, o que é bastante. Existem imagens ultra-leves que deixam apenas o que é estritamente necessário; por exemplo, a imagem Alpine Linux ocupa apenas 5MB. Ainda assim, é um peso extra para cada aplicação.

As soluções acima mostram como mitigar o risco de uma árvore de dependências frágil.

Segurança de execução, sem contêineres

Esse ponto é mais complicado. Aqui, queremos limitar o acesso do programa ao sistema de arquivos e à rede.

Na maioria dos sistemas operacionais, o controle de acesso ao sistema de arquivos é a nível de usuário. Para fazer com que um programa só possa acessar determinados arquivos e diretórios, é preciso criar um usuário (ou grupo de usuários) com essas regras e então fazer com que o programa seja sempre executado a partir desse usuário.

Já a restrição de comunicação de rede é feita via firewall, com controle de acesso a nível de usuários e programas.

Proposta: Manifestos de execução

Uma sugestão para sistemas operacionais seria ter manifestos de execução, que definem claramente como um programa é executado e as permissões dele no sistema.

O manifesto de execução poderia ainda definir com quais dispositivos e periféricos o programa interage. Ou seja, poderia ser útil também para programas desktop, com interfaces gráficas.

Esse arquivo poderia ser assinado com um par de chaves pública-privada para garantia de autenticidade. Um hash verificaria se o executável corresponde ao esperado pelo manifesto.

manifestVersion: v1
author: myCompany
name: myApp
run: ./myapp
hash: <hash_do_executável> # opcional

allowedDirectories:
  - name: appDir
    path: ./**/ # todos os subdiretórios
    permission: read
  - name: sharedFolder
    path: \\EnvGeoServer\Repository\Tools\admin\
    permission: readWrite

allowedNetwork:
  - name: localhost
    direction: inbound
    ip: 127.0.0.1
    protocol: tcp
    port: 8080

allowedDevices:
  - mouse
  - keyboard
  - audioOut
  - display

Fontes e leituras interessantes

Logs estruturados em .NET com NativeAOT

2025-04-15T00:00:00Z

NativeAOT e trimming são duas novas opções de compilação em .NET que surgiram nos últimos anos, proporcionando executáveis menores, mais rápidos e com menor consumo de memória RAM. Resumidamente, o NativeAOT compila direto para código nativo de máquina e o trimming remove trechos de código desnecessários.

Para aplicar essas opções, é necessário que todos os caminhos de código sejam analisáveis estaticamente, ou seja, não pode haver uso de reflection na aplicação, sob o risco de ter partes importantes removidas acidentalmente e haver comportamentos indesejáveis durante a execução.

A maioria das bibliotecas de logging atualmente (12/04/2025) trabalha com reflection, principalmente para suportar logs estruturados. Neste artigo, vamos ver como fazer um logger estruturado customizado, compatível com NativeAOT e trimming.

Logs estruturados

Em um log estruturado, as mensagens ficam em uma estrutura de chaves-valores, como JSON ou XML. Esse formato permite que elas sejam facilmente processadas por bancos de dados e motores de logs.

Considere o exemplo abaixo:

string municipio = "Bento Gonçalves / RS";

PrevisaoTempo previsao = new(
    tempMin: 16,
    tempMax: 21,
    chuvaMm: 32.5,
    ventoKmh: 6);

using (logger.BeginScope("{@PrevisaoTempo}", previsao))
{
    logger.LogInformation(
        "Previsão do tempo para {Municipio} em {Data}",
        municipio, DateTime.Today);
}

Log estruturado em JSON:

{
  "Timestamp": "2025-04-12T20:25:57.8532799Z",
  "Level": "Information",
  "Template": "Previsão do tempo para {Municipio} em {Data}",
  "Municipio": "Bento Gonçalves / RS",
  "Data": "2025-04-13",
  "@PrevisaoTempo": {
    "TemperaturaMinimaEmC": 16,
    "TemperaturaMaximaEmC": 21,
    "ChuvaEmMm": 32.5,
    "VentoEmKmH": 6
  }
}

Quando um parâmetro entre chaves tem arroba ('@') no início, trata-se de um objeto complexo e suas propriedades internas são lidas como chave-valor. Quando não há arroba, trata-se de um valor simples, como um número, um Guid ou uma string.

Os escopos são informações complementares ao log, que podem ser relevantes.

Interface `ILogger` em .NET

O .NET moderno faz uso extensivo da interface Microsoft.Extensions.Logging.ILogger. Ela é descrita abaixo (código-fonte):

namespace Microsoft.Extensions.Logging;

public interface ILogger
{
    void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter);

    bool IsEnabled(LogLevel logLevel);

    IDisposable? BeginScope<TState>(TState state) where TState : notnull;
}

Apesar de não estar explícito na interface, o TState quase sempre é um tipo que herda de IReadOnlyList<KeyValuePair<string, object?>>, isso é verificável pelo próprio código-fonte do .NET runtime: classe LoggerExtensions e classe FormattedLogValues.

O TState contém pares de chave-valor, incluindo o template da mensagem e valores dos parâmetros. Isso vale tanto para o TState do método Log como do método BeginScope.

Logger sem reflection

A questão aqui é como formatar uma mensagem de log de forma genérica e sem usar reflection.

Como solução, vamos fazer um log em JSON com o apoio de source generators. No JsonSerializerContext a ser usado no nosso logger, precisaremos incluir todos os tipos de objeto que possam vir como parâmetros de log.

Considerações

Nosso logger implementará a interface ILogger.
Consideraremos que o TState sempre herda de IReadOnlyList<KeyValuePair<string, object?>>.
Filtraremos as mensagens para pegar apenas as relevantes, de modo a também diminuir a quantidade de tipos adicionados ao JsonSerializerContext. Isso é importante principalmente para projetos ASP.NET.
Neste exemplo, a saída de log será no console.
Usaremos o formato CLEF.
O scopeProvider é responsável por ler os escopos capturados. Usaremos a implementação padrão LoggerExternalScopeProvider.

Código

No setup do HostBuilder / WebApplicationBuilder (Program.cs):

webAppBuilder.Logging
    .ClearProviders()
    .AddProvider(new ClefLoggerProvider());

Logger provider:

public sealed class ClefLoggerProvider : ILoggerProvider
{
    public ILogger CreateLogger(string categoryName) =>
        new ClefLogger(categoryName, new LoggerExternalScopeProvider());

    public void Dispose() { }
}

No JsonSerializerContext:

[JsonSerializable(typeof(Dictionary<string, object?>))]
[JsonSerializable(typeof(double))]
[JsonSerializable(typeof(long))]
// adicionar tipos aqui, por exemplo:
[JsonSerializable(typeof(PrevisaoTempo))]
// opções de JSON
[JsonSourceGenerationOptions(
    WriteIndented = false,
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
public partial class AppJsonSrcGenContext : JsonSerializerContext
{
}

Logger:

public sealed class ClefLogger(
    string categoryName,
    IExternalScopeProvider? scopeProvider) : ILogger
{
    private static readonly string[] logsParaIgnorar = [
        "Request starting",
        "Executing",
        "Setting HTTP status code",
        "Executed",
        "Writing value",
        "Write content",
        "Sending file",
        "Request reached the end of the middleware pipeline without being handled by application code."
    ];

    public IDisposable? BeginScope<TState>(TState state)
        where TState : notnull =>
        scopeProvider?.Push(state) ?? default;

    public bool IsEnabled(LogLevel logLevel) => true;

    private static bool FiltrarPropriedades(KeyValuePair<string, object?> kv) =>
        kv.Key != "{OriginalFormat}"
        && kv.Value != null
        && (kv.Value is string s ? !string.IsNullOrEmpty(s) : true);

    private static bool DeveIgnorarLog(string? originalFormat) =>
        originalFormat is null || logsParaIgnorar.Any(originalFormat.StartsWith);

    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
    {
        if (state is not IEnumerable<KeyValuePair<string, object?>> msgProps)
            return;

        string? originalFormat = (string?)msgProps.FirstOrDefault(kv => kv.Key == "{OriginalFormat}").Value;

        if (DeveIgnorarLog(originalFormat))
            return;

        List<IEnumerable<KeyValuePair<string, object?>>>? scopes = new();
        scopeProvider?.ForEachScope((scope, st) =>
        {
            if (scope is IEnumerable<KeyValuePair<string, object?>> scopeItems)
            {
                scopes.Add(scopeItems.Where(FiltrarPropriedades));
            }
        }, state);

        IEnumerable<KeyValuePair<string, object?>> standardProps =
        [
            new("@i", eventId.Name),
            new("@t", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ")),
            new("@c", categoryName),
            new("@l", Enum.GetName(logLevel)),
            //new("@m", formatter(state, exception)),
            new("@mt", originalFormat),
            new("@x", exception?.ToString())
        ];

        var msg = standardProps
            .Concat(msgProps.Where(FiltrarPropriedades))
            .Concat(scopes.SelectMany(x => x))
            // evitando chaves repetidas
            .DistinctBy(kv => kv.Key)
            // remover nulos para JSON
            .Where(x => x.Value is not null)
            .ToDictionary();

        try
        {
            EscreverLinhaLog(msg);
        }
        catch (Exception jsonEx)
        {
            msg = standardProps
                .Append(new("AVISO", "Não foi possível serializar mensagem original em JSON."))
                .Append(new("JsonException", jsonEx.ToString()))
                // remover nulos para JSON
                .Where(x => x.Value is not null)
                .ToDictionary();

            EscreverLinhaLog(msg);
        }
    }

    // TODO: Usar fila para evitar concorrência
    // Mudar saída se quiser: arquivo, motor de logs, etc.
    private void EscreverLinhaLog(Dictionary<string, object?> msg)
    {
        string json = JsonSerializer.Serialize(msg, AppJsonSrcGenContext.Default.DictionaryStringObject);
        Console.WriteLine(json);
    }
}

O logger acima funciona com NativeAOT e trimming habilitados.

Se houver algum erro de serialização de JSON, o bloco catch formata uma nova mensagem de log sem as propriedades e escopos (possíveis causadores do erro) e coloca a JsonException relativa ao problema.

Exemplo de log gerado

{
  "@t": "2025-04-15T12:09:58.4990143Z",
  "@c": "Microsoft.AspNetCore.Hosting.Diagnostics",
  "@l": "Information",
  "@mt": "Request finished {Protocol} {Method} {Scheme}://{Host}{PathBase}{Path}{QueryString} - {StatusCode} {ContentLength} {ContentType} {ElapsedMilliseconds}ms",
  "ElapsedMilliseconds": 124.2172,
  "StatusCode": 201,
  "ContentType": "application/json; charset=utf-8",
  "Protocol": "HTTP/2",
  "Method": "POST",
  "Scheme": "https",
  "Host": "localhost:5001",
  "Path": "/",
  "RequestId": "0HNBS2ORC5B08:00000001",
  "RequestPath": "/"
}

Fontes e links interessantes

Método dos mínimos quadrados com programação funcional

2025-03-07T00:00:00Z

Suponha que você tenha um conjunto de dados numéricos e queira formar uma estimativa futura a partir deles. Alguns exemplos:

Preço de um produto;
Demanda e produção históricas;
Cotação de ativos financeiros;
Calibração de uma máquina ao longo do tempo;
Concentração de reagentes e produtos químicos;
Velocidade de propagação de uma doença;
Volume de reservatórios de água;
Demanda de energia elétrica;
Consumo de combustível.

O método dos mínimos quadrados é uma ferramenta matemática que gera uma equação próxima de medições existentes. Diversas curvas podem ser aproximadas, como lineares, polinomiais, exponenciais, logarítmicas e diversas outras.

Considere o gráfico abaixo, de vendas por mês. A linha azul é a aproximação linear e a linha vermelha corresponde às medições reais.

---
config:
    xyChart:
        width: 540
    themeVariables:
        xyChart:
            backgroundColor: "#00000000"
            plotColorPalette: "#C00, #22F"
---
xychart-beta
    title "Vendas por mês (R$)"
    x-axis "mês" [1,2,3,4,5,6,7,8,9,10,11,12]
    y-axis 0 --> 50000
    line [17000, 24000, 16000, 30000, 35000, 26000, 29000, 40000, 44000, 35000, 41000, 47000]
	line [18461.538, 20923.076, 23384.614, 25846.152, 28307.690, 30769.228, 33230.766, 35692.304, 38153.842, 40615.380, 43076.918, 45538.456]
	%% =2461,538 * x + 16000

Base teórica

Considere f(x) sendo a equação que queremos gerar e (x_i, y_i) as medições coletadas. A melhor equação é aquela cujas diferenças entre aproximações e medições sejam as menores possíveis; em outras palavras:

|f(x_i) − y_i| é a distância entre aproximação e realidade;
Σ é o somatório.
Σ|f(x_i) − y_i| deve ser o mais próximo de zero.

Vamos chamar de SQE a soma dos quadrados dos erros: SQE = Σ(f(x_i) − y_i)². Como o objetivo é "medir a distância" entre aproximação e realidade, é mais fácil elevarmos a diferença ao quadrado, ao invés de aplicar o módulo.

Precisamos aplicar módulo ou elevar ao quadrado para medição de distância pois uma subtração simples poderia resultar em um valor negativo, e não existe distância negativa.

O mínimo de SQE depende do tipo de função que queremos aproximar:

Linear: f(x) = ax + b
Exponencial: f(x) = a ⋅ e^bx
Potencial: f(x) = ax^b
Logarítmica: f(x) = a + b ⋅ ln(x)

Substituindo f(x) pelas funções acima em SQE, teremos que ela depende das variáveis a e b. No caso da aproximação linear: SQE(a,b) = Σ(ax_i + b − y_i)². x_i e y_i são constantes, por serem pré-fornecidos.

O mínimo de uma função fica no ponto em que sua derivada (leia-se inclinação) é igual a zero:

---
config:
    xyChart:
        width: 540
    themeVariables:
        xyChart:
            backgroundColor: "#00000000"
            plotColorPalette: "#CC0000, #f59316, #f59316, #f59316"
---
xychart-beta
    title "y = x²"
    x-axis "x" -6 --> 6
    y-axis "y" 0 --> 40
    line [36,25,16,9,4,1,0,1,4,9,16,25,36]
	line [27,21,15,9,3,-3,-9,-15,-21,-27,-33,-39,-45]
    line [0,0,0,0,0,0,0,0,0,0,0]
    line [-45,-39,-33,-27,-21,-15,-9,-3,3,9,15,21,27]

Em vermelho: y = x². Em laranja: as derivadas (retas de inclinação) em x = −3, 0 e 3.

Temos que SQE vai ter seu ponto mínimo onde as derivadas parciais em relação a a e b tiverem valor zero, resolvendo o sistema de equações:

∂SQE(a,b) / ∂a = 0

∂SQE(a,b) / ∂b = 0

Essa é a base teórica do método dos mínimos quadrados. Se você ficou interessado e quer se aprofundar na teoria, há links no final desta página com explicações adicionais sobre o assunto. Particularmente, recomendo esta aula da UFPR.

Programação funcional

A programação funcional é um paradigma que foca nas transformações dos dados: como em uma função matemática, um valor x entra e é transformado por f(x). Num código funcional, transformações muitas vezes são aplicadas em cascata, ex.: f(g(h(x))).

Neste artigo, vamos usar a linguagem F#, que usa o runtime .NET.

Este post explica como montar seu ambiente e tem dicas de sintaxe da linguagem.

Aproximação linear

A equação gerada será do tipo f(x) = ax + b.

Tendo um conjunto de valores medidos (x_i, y_i), a e b são calculados por:

O código em F# abaixo calcula a aproximação linear.

x e y são os valores de entrada.
Seq.sumBy soma os resultados de uma função aplicada aos valores de uma seqüência:
- x = [1, 2, 3]
- x |> Seq.sumBy(fun i -> 2 * i) = 12
- (2*1 + 2*2 + 2*3 = 12)
Seq.zip forma uma seqüência de pares vindos de duas outras seqüências. Por exemplo:
- x = [1, 2, 3]
- y = [9, 8, 7]
- Seq.zip(x)(y) = [ (1, 9), (2, 8), (3, 7) ]

// s = soma
let s(v: double[]): double =
    v |> Seq.sum

// sm = soma de multiplicações
let sm(v1: double[])(v2: double[]): double =
    Seq.zip(v1)(v2)
    |> Seq.sumBy (fun (x, y) -> x * y)

let aproximacaoLinear(x: double[])(y: double[]): (double * double) =
    let n = x.Length |> double
    let sx = s(x)
    let sx2 = sm(x)(x)
    let sy = s(y)
    let sxy = sm(x)(y)
    let d = n*sx2 - sx**2
    let a = (n*sxy - sx*sy)/d
    let b = (sx2*sy - sxy*sx)/d
    (a,b)

Aproximação exponencial

A equação gerada será do tipo f(x) = A ⋅ e^bx.

e é a base natural, aproximadamente igual a 2,71828.

Tendo um conjunto de valores medidos (x_i, y_i), a e b são calculados por:

O código em F# abaixo calcula a aproximação exponencial.

ln é o logaritmo natural, na base e.
A = e^a.
Seq.zip3 segue a mesma lógica que o Seq.zip, porém forma uma seqüência de trios vindos de três outras seqüências.
Importante: os valores de y precisam ser todos maiores do que zero, pois não existe logaritmo de valor zero ou negativo.

// s = soma
let s(v: double[]): double =
    v |> Seq.sum

// sm = soma de multiplicações
let sm(v1: double[])(v2: double[]): double =
    Seq.zip(v1)(v2)
    |> Seq.sumBy (fun (x, y) -> x * y)

let ln = System.Math.Log

// smm = soma(v1 * v2 * v3)
let smm(v1: double[])(v2: double[])(v3: double[]): double =
    Seq.zip3(v1)(v2)(v3)
    |> Seq.sumBy (fun (a,b,c) -> a * b * c)

// smln = soma(v1 * ln(v2))
let smln(v1: double[])(v2: double[]): double =
    Seq.zip(v1)(v2)
    |> Seq.sumBy (fun (a,b) -> a * ln(b))

// smmln = soma(v1 * v2 * ln(v3))
let smmln(v1: double[])(v2: double[])(v3: double[]): double =
    Seq.zip3(v1)(v2)(v3)
    |> Seq.sumBy (fun (a,b,c) -> a * b * ln(c))

// exponencial: y = A * e^(b*x)
let aproximacaoExponencial(x: double[])(y: double[]): (double * double) =
    let sx2y = smm(x)(x)(y)
    let sylny = smln(y)(y)
    let sxy = sm(x)(y)
    let sxylny = smmln(x)(y)(y)
    let sy = s(y)
    let d = sy*sx2y - sxy**2
    let a = (sx2y*sylny - sxy*sxylny)/d
    let b = (sy*sxylny - sxy*sylny)/d
    let A = System.Math.Exp(a)
    (A, b)

Caso de estudo: Mineração de prata

Mina Pirquitas, Jujuy, Argentina.

Vamos extrair dados do site Our World in Data sobre a mineração mundial de prata, entre 1900 e 2023, e vamos fazer as aproximações linear e exponencial.

Arquivo CSV disponível neste link.

Resultados:

f(x) é a mineração em toneladas, x é o ano.
Linear: f(x) = 162,897x − 308090,816
Exponencial: f(x) = 0,000000002257 ⋅ e^0,01485166x

---
config:
    xyChart:
        width: 540
    themeVariables:
        xyChart:
            backgroundColor: "#00000000"
            plotColorPalette: "#CC0000, #2222FF, #00CC00"
---
xychart-beta
    title "Produção anual de prata (ton. mét.)"
    x-axis "Ano" 1900 --> 2023
    y-axis 0 --> 30000
    line [ 5400, 5380, 5060, 5220, 5110, 5360, 5130, 5730, 6320, 6600, 6900, 7040, 6980, 7010, 5240, 5730, 5250, 5420, 6140, 5490, 5390, 5330, 6530, 7650, 7450, 7650, 7890, 7900, 8020, 8120, 7740, 6080, 5130, 5340, 5990, 6890, 7920, 8640, 8320, 8300, 8570, 8140, 7780, 6380, 5740, 5040, 3970, 5220, 5440, 5570, 6320, 6210, 6700, 6900, 6670, 7000, 7020, 7190, 7430, 6910, 7320, 7370, 7650, 7780, 7730, 8010, 8300, 8030, 8560, 9200, 9360, 9170, 9380, 9700, 9260, 9430, 9840, 10300, 10700, 10800, 10700, 11200, 11500, 12100, 13100, 13100, 13000, 14000, 15500, 16400, 16600, 15600, 14900, 14100, 14000, 14900, 15100, 16500, 17200, 17600, 18100, 18700, 18800, 18800, 20000, 20800, 20100, 20800, 21300, 22300, 23300, 23300, 24300, 26700, 28000, 27600, 28600, 26500, 25900, 25800, 23500, 25000, 25600, 26000 ]
	line [ 1413.484, 1576.381, 1739.278, 1902.175, 2065.072, 2227.969, 2390.866, 2553.763, 2716.66, 2879.557, 3042.454, 3205.351, 3368.248, 3531.145, 3694.042, 3856.939, 4019.836, 4182.733, 4345.63, 4508.527, 4671.424, 4834.321, 4997.218, 5160.115, 5323.012, 5485.909, 5648.806, 5811.703, 5974.6, 6137.497, 6300.394, 6463.291, 6626.188, 6789.085, 6951.982, 7114.879, 7277.776, 7440.673, 7603.57, 7766.467, 7929.364, 8092.261, 8255.158, 8418.055, 8580.952, 8743.849, 8906.746, 9069.643, 9232.54, 9395.437, 9558.334, 9721.231, 9884.128, 10047.025, 10209.922, 10372.819, 10535.716, 10698.613, 10861.51, 11024.407, 11187.304, 11350.201, 11513.098, 11675.995, 11838.892, 12001.789, 12164.686, 12327.583, 12490.48, 12653.377, 12816.274, 12979.171, 13142.068, 13304.965, 13467.862, 13630.759, 13793.656, 13956.553, 14119.45, 14282.347, 14445.244, 14608.141, 14771.038, 14933.935, 15096.832, 15259.729, 15422.626, 15585.523, 15748.42, 15911.317, 16074.214, 16237.111, 16400.008, 16562.905, 16725.802, 16888.699, 17051.596, 17214.493, 17377.39, 17540.287, 17703.184, 17866.081, 18028.978, 18191.875, 18354.772, 18517.669, 18680.566, 18843.463, 19006.36, 19169.257, 19332.154, 19495.051, 19657.948, 19820.845, 19983.742, 20146.639, 20309.536, 20472.433, 20635.33, 20798.227, 20961.124, 21124.021, 21286.918, 21449.815 ]
	line [ 4059.94, 4120.69, 4182.34, 4244.92, 4308.44, 4372.90, 4438.33, 4504.74, 4572.14, 4640.55, 4709.99, 4780.46, 4851.99, 4924.58, 4998.27, 5073.06, 5148.96, 5226.00, 5304.20, 5383.56, 5464.11, 5545.87, 5628.85, 5713.07, 5798.55, 5885.31, 5973.37, 6062.75, 6153.46, 6245.53, 6338.98, 6433.83, 6530.10, 6627.80, 6726.97, 6827.62, 6929.78, 7033.47, 7138.71, 7245.52, 7353.93, 7463.96, 7575.64, 7689.00, 7804.04, 7920.81, 8039.32, 8159.61, 8281.70, 8405.62, 8531.39, 8659.04, 8788.60, 8920.10, 9053.56, 9189.03, 9326.52, 9466.07, 9607.70, 9751.46, 9897.36, 10045.45, 10195.76, 10348.31, 10503.15, 10660.30, 10819.81, 10981.70, 11146.01, 11312.78, 11482.05, 11653.85, 11828.22, 12005.20, 12184.83, 12367.15, 12552.19, 12740.00, 12930.62, 13124.10, 13320.47, 13519.78, 13722.07, 13927.38, 14135.77, 14347.28, 14561.95, 14779.83, 15000.97, 15225.43, 15453.24, 15684.46, 15919.13, 16157.32, 16399.08, 16644.45, 16893.49, 17146.26, 17402.81, 17663.20, 17927.49, 18195.73, 18467.98, 18744.31, 19024.77, 19309.43, 19598.34, 19891.58, 20189.21, 20491.29, 20797.89, 21109.08, 21424.93, 21745.50, 22070.86, 22401.10, 22736.28, 23076.47, 23421.75, 23772.20, 24127.89, 24488.90, 24855.32, 25227.21 ]
	%% linear: 162,897 * ano - 308090,816
	%% exponencial: =(0,000000002257)*e^(ano*0,01485166)

Linha vermelha: produção anual; linha azul: aproximação linear; linha verde: aproximação exponencial.

Fontes e leituras interessantes

Interfaces como princípio de engenharia

2025-02-20T00:00:00Z

Uma interface é o modo como duas coisas diferentes se comunicam.

Em engenharia, interfaces são muito úteis para abstrair a lógica macro de um sistema. Com elas, componentes podem focar em funções específicas e as interfaces definem como eles se conectam.

flowchart LR
  A
  B
  subgraph S[S]
    direction RL
    a
    b
  end
  a-.->A  
  b-.->B
  classDef abstract stroke:#f66,stroke-width:2px,stroke-dasharray: 5 5
  class a,b abstract;

No diagrama acima, o sistema S delega as tarefas a e b para os componentes A e B, respectivamente. As setas representam interfaces.

Vamos analisar aqui benefícios das interfaces com um olhar para produtos de engenharia de modo geral.

Reúso

Interfaces permitem que um componente seja projetado para atender mais de um sistema.

Reaproveitamento

O raciocínio é parecido com o do reúso, porém, o reúso trata da concepção de um componente visando atender vários casos de uso; reaproveitamento trata-se de usar um componente já existente, ao invés de criar um novo.

Intercambialidade

Partes podem ser trocadas por outras equivalentes.

Paralelismo de trabalho

Times distintos podem trabalhar em paralelo nas partes, entregando mais rapidamente o produto final.

Dissipação de risco

Está relacionado ao paralelismo de trabalho. Problemas em uma frente de trabalho não afetam outras frentes.

Custos de maquinário

A produção de uma peça requer máquinas, que custam dinheiro. Repassar a produção para outros evita esse custo.

Especialização

Times e empresas com conhecimentos específicos sobre um tipo de componente os produzem com melhor qualidade.

Testes unitários

Interfaces possibilitam testes de forma isolada no componente, tal que as dependências externas são substituídas por simulações ou imitações — em inglês, mocks. Por serem testes individualizados, há mais atenção e foco no componente em si, além de não ser necessário ter todo o sistema pronto para então validá-lo.

Isso também contribui para o shift-left testing, que é a idéia de antecipar validações no fluxo de trabalho: ao realizar testes isoladamente, problemas ficam visíveis mais cedo no processo.

Comparação entre abordagens de testes shift-left e tradicional.

Exemplos de interfaces em engenharia

Computadores

O hardware dos computadores é extremamente modular, o que facilita trocar partes em manutenções e upgrades.

Diagrama da placa-mãe de um computador.

Qualquer processador que tenha o mesmo soquete que a placa-mãe pode ser usado;
Qualquer pente de memória RAM que tenha o mesmo soquete (ex.: DIMM, SO-DIMM) e mesma classe (ex.: DDR3, DDR4, DDR5) que a placa-mãe é aceito;
Qualquer dispositivo com interface SATA é aceito: discos rígidos, leitoras de CD/DVD.
Qualquer fonte de energia pode ser usada, desde que forneça através do conector correspondente da placa-mãe (ex.: ATX).
Por fim, uma placa-mãe pode ser trocada reaproveitando as demais partes.

Redes elétricas e hidráulicas

Instalações elétricas e hidráulicas também são altamente modularizadas.

Disjuntores elétricos e registros hidráulicos permitem que subsistemas sejam isolados e reparados sem afetar outros.
Terminais podem ser substituídos com facilidade.
- Para elétrica: tomadas, lâmpadas, interruptores, disjuntores; basta atender à tensão (voltagem) e corrente máxima (amperagem).
- Para hidráulica: sifões, torneiras, chuveiros - basta atender ao tamanho das conexões.
A exceção é reparos dentro da alvenaria, como em conduítes e encanamentos, porém, problemas neles tendem a ser mais raros.

Possíveis contrapartidas

Eficiência energética e material

Conexões consomem energia e material, na construção e na operação. Em componentes condensados ou com ligações diretas, essas perdas são mitigadas ou até mesmo eliminadas.

Coesão do sistema

Em toda conexão, há o risco de descasamento entre as partes. Diminuir o número de intermediários torna o sistema mais coeso.

Liberdade de inovação

Interfaces definidas por terceiros podem não atender da melhor forma possível um caso de uso em questão. Nessas situações, pode ser interessante romper padrões de mercado e criar suas próprias interfaces.

Caso de estudo: Querosene de aviação em aeroportos

Aeroportos precisam de querosene de aviação (QAV) para abastecer as aeronaves.

Em aeroportos pequenos e médios, o QAV chega aos reservatórios via caminhões-tanque, que saem das distribuidoras. Porém, em aeroportos grandes e com alto consumo de combustível, o QAV chega via dutos que saem diretamente das refinarias, chamados de querodutos.

Os querodutos são caros de serem construídos, porém a demanda elevada justifica e a operação acaba sendo mais barata e eficiente do que usar caminhões-tanque.

Durante a greve dos caminhoneiros de 2018, aeroportos brasileiros que dependiam de caminhões-tanque sofreram com escassez de combustível e alguns tiveram suas atividades paralisadas. Já os aeroportos servidos por querodutos, Cumbica e Galeão, continuaram funcionando normalmente.

Conclusão

O conceito de interfaces vem da idéia de partes intercambiáveis e sua utilização resulta em sistemas melhores, mais confiáveis, mais baratos, de manutenção mais fácil e mais rápidos de serem desenvolvidos. Além disso, contribuem para o reúso de partes, evitando que sistemas precisem ser trocados por inteiro.

Em alguns casos, contudo, desenhar sua própria interface, ou então "cortar o intermediário", pode tornar o sistema mais coeso e eficiente.

Fontes e leituras interessantes

Introdução ao FFmpeg

2025-01-13T00:00:00Z

Introdução

Sabe aquele vídeo engraçado que você viu na Internet? Ou o filme que assistiu no cinema? Se você assistiu um vídeo digital nos últimos 15 anos, há grandes chances de ele ter passado pelo FFmpeg em algum momento, seja para edição, reprodução ou distribuição.

O FFmpeg é um programa de transformação de vídeo e áudio que é usado por diversas empresas de multimídia, como YouTube, TikTok e Vimeo.

Neste artigo, vamos aprender como usá-lo, através de exemplos práticos.

Índice

Instalação do FFmpeg

Linux

Debian / Ubuntu:

sudo apt update
sudo apt install ffmpeg
ffmpeg -version

Fedora:

sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf upgrade --refresh
sudo dnf install ffmpeg --allowerasing
sudo dnf install ffmpeg-devel --allowerasing
ffmpeg -version

Arch Linux:

sudo pacman -Sy 
sudo pacman -S ffmpeg 
ffmpeg -version

macOS

Instalar o Brew.
Executar no Terminal:

brew update
brew install ffmpeg
ffmpeg -version

Windows

Você pode instalar via Winget (disponível para Windows 11, Windows Server 2025):

winget install --id=Gyan.FFmpeg -e

Ou instalar manualmente:

Baixar a versão mais recente do FFmpeg para Windows (link). A versão essentials é a mais indicada para a maioria dos usuários.
Descompactar o zip baixado.
Adicionar o caminho da pasta bin ao PATH. Para isto:
- No Windows Explorer, clicar com o botão direito do mouse em Este Computador > Propriedades.
- Na janela que se abriu, clicar em Configurações avançadas do sistema.
- Em Propriedades do sistema, clicar em Variáveis de Ambiente....
- Em Variáveis de usuário para X, selecionar a linha com Path e clicar em Editar....
- Adicionar o caminho da pasta na lista. Vai ser algo como: C:\Users\usuario\Downloads\ffmpeg-7.0.1-essentials_build\bin (alterar para o caminho na sua máquina).
- Clicar em OK nas janelas para salvar as alterações.

Como usar

O FFmpeg é usado via Terminal, Prompt de Comando ou PowerShell. No seu computador, abra um desses programas.
Nos exemplos, os arquivos são especificados sem a pasta, o que implica a pasta atual da linha de comando. Para mudar o diretório atual:

cd C:\Users\usuario\Videos\

Se os arquivos estão (ou serão gerados) em outras pastas, é necessário passar o caminho completo do arquivo, por exemplo:

ffmpeg -i "C:\Vídeos\entrada.mov" -c copy "C:\Vídeos\saida.mp4"

Operações

Mudar formato do arquivo

Os formatos de vídeo geralmente são apenas contêineres de transporte, sendo que o conteúdo em si é determinado pelos codecs. Exemplos de contêineres: MP4, AVI, MKV, MOV, WebM.

Os codecs de vídeo mais populares são:

H.264, é o mais antigo e com maior suporte de plataformas.
H.265, é mais recente e resulta em tamanho até 50% menor do que o H.264, porém, alguns navegadores Web e players não têm compatibilidade com ele.
AV1 é um codec novo. Ele tem licença de uso livre e promete compressão mais rápida e melhor do que o H.265, entretanto, o FFmpeg não o suporta plenamente ainda (06/01/2025).
VP9, usado em vídeos .webm e pelo YouTube.

Os principais codecs de áudio são:

MP3, amplamente suportado, tem boa compressão e poucas perdas (lossy).
AAC, usado no MP4, tem compressão e qualidade um pouco melhores do que o MP3.
Opus, lossy com boa qualidade.
FLAC, é um codec com compressão sem perdas (lossless).

Conversão de formato mantendo os codecs:

ffmpeg -i entrada.mov -c copy saida.mp4

Conversão de formato e de codecs (transcoding).

-c:v: codec de vídeo
-c:a: codec de áudio
-b:a: bitrate do áudio

ffmpeg -i entrada.mov -c:v h264 -c:a libopus -b:a 96k saida.mp4

Extrair áudio de um vídeo

Extração total, mantendo o codec de áudio:

MP4 -> AAC ou M4A
MKV -> diversos
WebM -> Opus ou Ogg Vorbis
MOV -> ALAC

ffmpeg -i entrada.mp4 -vn -c:a copy saida.m4a

Extração com transcoding (mudança de codec). -q:a é a qualidade, de 0 a 9; quanto menor, melhor a qualidade.

ffmpeg -i entrada.mp4 -vn -c:a libmp3lame -q:a 2 saida.mp3

Extração do áudio de um trecho do vídeo. -ss é o início, -to é o fim.

ffmpeg -i entrada.mp4 -ss 00:00:07 -to 00:00:10.7 -vn -c:a libmp3lame -q:a 2 saida.mp3

Diminuir tamanho do arquivo

Existem várias formas de se reduzir o tamanho de um vídeo. Nesta seção, abordaremos compressão.

Para entender a fundo o funcionamento, recomendo ler a documentação oficial dos codecs (exemplos: H.264 e H.265).

Limitar com CRF. A flag -crf, Constant Rate Factor, controla a qualidade e valor menor significa menos compressão e mais qualidade. A escala é de 0 a 51, valor padrão 23.

ffmpeg -i entrada.mp4 -c:v libx264 -crf 23 -pix_fmt yuv420p -c:a copy saida.mp4

-pix_fmt yuv420p é necessário para compatibilidade com o Apple QuickTime e alguns outros players.

Limitar o bitrate. Pode-se colocar um limite no bitrate do vídeo, tornando seu tamanho mais previsível. Essa opção pode ser combinada com o CRF. No exemplo abaixo, o encoder procura limitar o bitrate máximo em 1Mbit/s.

ffmpeg -i entrada.mp4 -c:v libx264 -crf 23 -maxrate 1M -bufsize 2M -pix_fmt yuv420p -c:a copy saida.mp4

Transcodar para codecs mais modernos. O H.265, por exemplo, produz arquivos menores do que o H.264. A escala do CRF aqui é de 0 a 51, com valor padrão 28.

Deve-se lembrar que não são todos os navegadores e players que suportam H.265.

ffmpeg -i entrada.mp4 -c:v libx265 -crf 28 -tag:v hvc1 -c:a copy saida.mp4

-tag:v hvc1 é para o vídeo gerado ter compatibilidade com o Apple QuickTime.

Cortar trecho do vídeo

ffmpeg -i entrada.mp4 -ss 00:00:19.4 -to 00:03:50 -c copy saida.mp4

Os parâmetros de tempo podem ser colocados antes ou depois do parâmetro de entrada.

Colocados antes (-ss -to -i), resulta-se em uma operação mais rápida pois o corte é na entrada, que depois é processada; porém, o corte pode ser impreciso e pode haver dissincronia entre o áudio e o vídeo.

Colocados depois (-i -ss -to), o corte é mais preciso e não há risco de dissincronia; contudo, a operação é mais lenta porque o corte é na saída, após todo o processamento do vídeo.

Em dúvida, pode-se experimentar primeiro o corte na entrada (primeira opção) e ver o resultado; se o resultado não for correto, então partir para o corte na saída (segunda opção).

Aumentar e diminuir volume de som

O exemplo abaixo aumenta o volume em 2,4 vezes.

Para reduzir à metade, valor 0,5 (usar ponto ao invés de vírgula).

ffmpeg -i entrada.mp4 -af "volume=2.4" saida.mp4

Redimensionar frames

Dimensões fixas, largura por altura:

ffmpeg -i entrada.mp4 -lavfi "scale='720:480'" saida.mp4

Uma dimensão fixada e a outra proporcional, para manter o aspecto:

ffmpeg -i entrada.mp4 -lavfi "scale='720:-2'" saida.mp4

Redução por proporções:

ffmpeg -i entrada.mp4 -lavfi "scale='floor(iw/4)*2:floor(ih/4)*2'" saida.mp4

No exemplo acima, usou-se a função floor(d/4) * 2 para calcular a metade porque alguns codecs requerem que as dimensões sejam sempre números pares.

Inserir legendas

Legendas opcionais

Também chamadas de legendas soft, aparecem ao clicar com o botão direito do mouse no player e escolher a legenda. Mais de uma pode ser adicionada, por exemplo, para mais de um idioma.

ffmpeg -i entrada.mp4 -i legendas.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng saida.mp4

Legendas fixas

Também chamadas de legendas hard ou burned.

legendas.srt é o arquivo de legendas. Alignment=2 significa posição centro inferior.

ffmpeg -i entrada.mp4 -lavfi "subtitles=legendas.srt:force_style='Alignment=2,OutlineColour=&H100000000,BorderStyle=3,Outline=1,Shadow=0,Fontsize=18,MarginL=5,MarginV=25'" -crf 1 -c:a copy saida.mp4

Exemplo de resultado:

Colocar texto em cima do vídeo

Usaremos o pad e o drawtext.

O pad coloca uma camada ao redor do vídeo; no exemplo abaixo, faremos de côr preta em cima do vídeo. Para isso, estenderemos a altura do frame em 100 e desenharemos a camada entre 0 e 100 na direção vertical:

# ih = input height
"pad=width=iw:height=(ih+100):x=0:y=100:color=black"

O drawtext desenhará o texto na camada. Nosso texto terá duas linhas, então, usaremos ele duas vezes.

x=(w-text_w)/2 centraliza horizontalmente o texto. A coordenada y determina a posição vertical da linha.

"drawtext=:font='Arial':text='Men′s Volleyball 2016 Olympics':fontsize=24:fontcolor=white:x=(w-text_w)/2:y=25"

"drawtext=:font='Arial':text='BRA 3 - 0 ITA':fontsize=24:fontcolor=white:x=(w-text_w)/2:y=54"

Comando:

ffmpeg -i entrada.mp4 -lavfi "format=yuv420p,pad=width=iw:height=(ih+100):x=0:y=100:color=black, drawtext=:font='Arial':text='Men′s Volleyball 2016 Olympics':fontsize=24:fontcolor=white:x=(w-text_w)/2:y=25, drawtext=:font='Arial':text='BRA 3 - 0 ITA':fontsize=24:fontcolor=white:x=(w-text_w)/2:y=54" -c:v libx264 -crf 25 saida.mp4

format=yuv420p é necessário para compatibilidade com Apple QuickTime e alguns outros players.

Exemplo de resultado:

Inspecionar metadados

Detalha quais codecs foram usados, resolução e bitrate do áudio e do vídeo, dentre outras informações.

ffprobe video.mp4

Fontes e links interessantes

Propriedades especiais em projetos .NET

2024-12-17T00:00:00Z

Arquivos de projeto .NET

Certas configurações em projetos .NET modificam como o projeto é compilado, e a performance e tamanho dos programas publicados.

Essas configurações ficam nos arquivos .csproj (C#), .fsproj (F#) e .vbproj (VB.NET); também podem ser passadas via linha de comando, ao executar dotnet run, dotnet build e dotnet publish.

Em arquivos de projeto

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

Via linha de comando

dotnet publish `
  --configuration Release `
  --self-contained true `
  --runtime "linux-x64" `
  -p:PublishSingleFile=true `
  --output "./out/"

Propriedades

TargetFramework

Diz para quais versões do .NET seu projeto deve compilar. Geralmente, especifica-se apenas um TFM (target framework moniker), porém, se precisar atender a mais de uma versão do .NET, você pode especificar uma lista de TFMs, separados por ponto-e-vírgula (';').

<PropertyGroup>

  <!-- apenas um -->
  <TargetFramework>net8.0</TargetFramework>

  <!-- múltiplos. note o plural. -->
  <TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>

</PropertyGroup>

Nullable

Quando presente com valor true, avisa sempre que uma variável que pode ser nula for usada em um local que não aceita nulos.

Considere o código abaixo. Há um aviso de que um valor nulo pode acabar sendo passado para o método int.Parse(), método este que não aceita strings nulas.

Há quatro formas de resolver esse aviso:

Alterar a assinatura do método. Quando uma variável tem interrogação após o tipo (string?), significa que aceita nulos; sem interrogação (string), espera-se um valor não-nulo.

public int ConverterParaInt(string stringNumerica) =>
    int.Parse(stringNumerica);

Proteger via código contra valores nulos.

public int ConverterParaInt(string? stringNumerica)
{
    if (stringNumerica == null)
        throw new ArgumentNullException(nameof(stringNumerica));
    else
        return int.Parse(stringNumerica);
}

Marcar com uma exclamação. Ela indica que o valor é seguro.

public int ConverterParaInt(string? stringNumerica) =>
    int.Parse(stringNumerica!);

Desabilitar a verificação de nuláveis via diretiva de compilação.

#nullable disable warnings

    public int ConverterParaInt(string? stringNumerica) =>
        int.Parse(stringNumerica);

#nullable restore warnings

ImplicitUsings

Faz com que todos os arquivos de código (.cs, .fs, .vb) venham com alguns usings declarados implicitamente, de modo que não é necessário declarar manualmente.

A lista de namespaces varia conforme o tipo de projeto.

Para projetos console e class libraries:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

Para projetos Web, além dos listados acima:

using System.Net.Http.Json;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

Para Workers, a primeira lista, mais:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

TreatWarningsAsErrors

Faz com que avisos sejam considerados erros e assim o projeto não compile se houver algum aviso.

<PropertyGroup>
  <TreatWarningsAsErrors>True</TreatWarningsAsErrors>
</PropertyGroup>

É uma opção interessante para melhorar a qualidade do código, pois força os desenvolvedores a se atentarem aos avisos, que indicam possíveis falhas de lógica e tratamento de dados. Um exemplo é combinar essa opção junto com o Nullable.

Comentário do autor: apenas isso como medida não tornará seu código melhor. Os devs podem simplesmente contornar os avisos, por exemplo, através de #pragma warning disable ou ignorar nuláveis via exclamação (ver acima). Um código de qualidade é resultado de boas práticas de programação e revisões por pares.

Configuration

Determina se o projeto vai ser compilado como Debug ou Release.

Em modo Debug, a compilação produz arquivos de símbolos (.pdb) que facilitam o debug do código via IDE e breakpoints. Além disso, o código não é optimizado plenamente.

No modo Release, a compilação não produz arquivos de símbolos e a optimização do código é total. Sempre que for gerar um programa para publicação, deve-se usar a configuração Release.

Essa opção é passada via flags.

SelfContained

Embute o .NET runtime junto ao executável publicado. Isso significa que a máquina de destino (onde o programa vai rodar) não precisará ter ele instalado.

Essa opção faz com que o tamanho do executável final seja maior (por ter o .NET runtime consigo).

PublishSingleFile

Condensa as várias DLLs e arquivos auxiliares do programa em um único arquivo executável, diminuindo a quantidade de arquivos publicados. Isso é interessante para programas portáteis (portable).

DLLs interop em C/C++ são imunes a essa opção e vão aparecer em arquivos separados.

<PropertyGroup>
  <PublishSingleFile>True</PublishSingleFile>
</PropertyGroup>

EnableCompressionInSingleFile

Junto com a opção acima, comprime o executável condensado, diminuindo seu tamanho no disco rígido. Um contraponto é que a inicialização do programa fica mais lenta, pois ele precisa descomprimir seu conteúdo antes de executar. (Ele não cria arquivos ao executar; a descompressão é feita em memória.)

<PropertyGroup>
  <EnableCompressionInSingleFile>True</EnableCompressionInSingleFile>
</PropertyGroup>

PublishReadyToRun

É uma optimização especial do compilador que torna a inicialização do programa mais rápida, prevendo como ele vai executar na máquina de destino e trocando partes de código intermedíario (IL, intermediate language) por código de máquina (Assembly). Isso é interessante para APIs, por exemplo, pois assim elas demoram menos tempo para entrar em funcionamento.

Essa opção aumenta o tamanho do executável final e aumenta o tempo de compilação.

<PropertyGroup>
  <PublishReadyToRun>True</PublishReadyToRun>
</PropertyGroup>

Trimming

Recorta partes não utilizadas do código e de bibliotecas do programa, diminuindo significativamente o tamanho do executável final.

Essa opção deve ser usada com cuidado, pois pode remover partes importantes do código e causar erros durante a execução. Para evitar esses problemas, o compilador emite avisos em linhas suscetíveis de serem recortadas, para que o programador adote alternativas ou então marque o código para não ser removido.

O recorte pode ser parcial, ou seja, só em classes e bibliotecas especificadas, ou então no programa inteiro.

Esse tema é extenso e requer uma leitura com atenção, por isso, recomendo a documentação.

Exemplo de trimming parcial:

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>partial</TrimMode>
</PropertyGroup>

<!-- lista de assemblies que serão trimmados -->
<ItemGroup>
  <TrimmableAssembly Include="MyAssembly" />
</ItemGroup>

NativeAOT

NativeAOT é um tipo especial de compilação direto para linguagem de máquina, aumentando a performance do programa.

Na compilação tradicional, o executável final é composto pelo código em linguagem intermediária (IL, intermediate language) que é interpretado pelo .NET runtime (CoreCLR). Durante a execução do programa, o runtime traduz cada instrução em IL para código de máquina, e assim o programa roda.

Ao compilar diretamente para linguagem nativa, o intermediário é removido e pode-se aproveitar diversas optimizações específicas de arquitetura de processador e sistema operacional, de modo que:

a execução fica mais rápida,
consome menos memória RAM,
o tamanho do executável final é menor.

Essa opção de compilação não é simples de usar, contudo. Ela requer que todos os caminhos de código possam ser analisados estaticamente, em outras palavras, não é possível usar reflection no programa, o que afeta por exemplo a serialização e desserialização de JSON e XML.

Para (des)serialização de JSON, uma solução é os source generators do System.Text.Json, que escrevem e lêem JSONs através de código gerado em tempo de compilação.

WPF e Windows Forms são baseados em reflection e por isso não suportam NativeAOT; mas aplicações console e ASP.NET minimal APIs têm suporte ao NativeAOT.

Assim como o trimming, usar essa funcionalidade requer cuidado e vale ler a documentação oficial.

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Version

Marca qual é a versão do programa, do arquivo ou do assembly.

<PropertyGroup>
  <Version>3.7.1</Version>
  <!-- o valor de Version é reutilizado abaixo -->
  <FileVersion>$(Version)</FileVersion>
  <AssemblyVersion>$(Version)</AssemblyVersion>
</PropertyGroup>

Para pegar a versão via código:

string versionName = Assembly.GetExecutingAssembly()
                             .GetName()
                             .Version?
                             .ToString(3);
// versionName = "3.7.1"

Aviso: o versionamento de pacotes NuGet é feito através de outras propriedades. Confira mais na documentação.

ApplicationIcon

Coloca um ícone no programa para exibição no Windows Explorer.

<PropertyGroup>
  <ApplicationIcon>my_program.ico</ApplicationIcon>
</PropertyGroup>

Fontes e leituras interessantes

Os pais da qualidade, Deming e Shewhart

2024-10-14T00:00:00Z

Nos anos 1980, havia um pensamento na cultura pop que o Japão conquistaria o mundo — não pela força, mas por sua economia pujante, que foi a segunda maior do mundo entre 1990 e 2010. Podemos ver isso em vários filmes, como no De Volta Para o Futuro Parte II, em que o chefe do Marty McFly no futuro é japonês; e em Duro de Matar, em que a esposa do protagonista trabalha numa empresa japonesa, no fim da década de 80. O chefe dela é o Sr. Takagi, na imagem abaixo.

A palavra-chave que resume o milagre econômico japonês é qualidade. Ao focar em produtos melhores, com menos defeitos e com processos industriais mais eficientes, a indústria japonesa ganhou a atenção dos consumidores e espaço na economia global.

Essa transformação começou com dois homens, cujos trabalhos mudaram o Japão e as empresas de todo o mundo.

Deming e Shewhart

William Edwards Deming (1900-1993) foi um estatístico, engenheiro, economista e consultor americano. Por seu trabalho, ele é conhecido como o pai da qualidade.

Deming fez graduação em engenharia elétrica, e depois mestrado e doutorado em matemática e física. Em 1927, ele começou a trabalhar no Departamento de Agricultura dos EUA e lá, por meio de colegas, conheceu Walter Andrew Shewhart (1891-1967), este que é conhecido como o pai do controle estatístico de qualidade. Shewhart era um engenheiro da Bell Telephone Company e usava estatística para melhorar a confiabilidade e clareza sonora das linhas telefônicas.

Shewhart ensinou a Deming muitas ferramentas que serviram de base para seus trabalhos futuros, dentre elas, os gráficos de controle e os ciclos PDCA.

Gráfico de controle

Mostra quanto algo fica dentro de uma margem de tolerância ao longo do tempo.

Alguns casos da vida real: o tamanho de peças mecânicas produzidas; a quantidade de remédio inserida em cada comprimido; o tempo de trajeto entre duas cidades.

Abaixo, vemos um processo que inicialmente está fora de controle; depois, fica dentro da zona de tolerância; e por fim, dentro de uma zona mais estreita, denotando melhora na qualidade do processo.

Com um gráfico de controle podemos detectar anomalias numa linha de produção, ou então estimar quando uma máquina precisará de manutenção.

Segunda Guerra Mundial e pós-guerra

Durante a Segunda Guerra Mundial, Deming fez parte do Comitê Técnico Emergencial dos EUA, focado em melhorar a indústria armamentícia. O controle estatístico de qualidade foi aplicado nas fábricas e diminuiu o número de falhas em armamentos americanos.

Após a guerra, Deming foi convocado para preparar o censo japonês de 1951 e seu trabalho e envolvimento na sociedade japonesa o fizeram ser notado, a ponto de a União Japonesa de Cientistas e Engenheiros (JUSE) chamá-lo para lhes ensinar sobre estatística e qualidade. Suas aulas foram um tremendo sucesso e foram transcritas em livros com milhares de cópias vendidas.

Em uma palestra a executivos japoneses em 1950, Deming lhes disse que implementar o controle estatístico de qualidade nas suas empresas diminuiria custos e desperdícios, aumentaria a produtividade e cativaria os consumidores, atraídos por produtos melhores. Os executivos levaram essas idéias para suas companhias e tiveram resultados muito positivos.

Nas décadas seguintes, o Japão viu sua economia ressurgir das cinzas e ganhar destaque mundial, em grande parte devido à implementação das idéias de Deming. O crescimento do PIB girava entre 8-10% ao ano.

Deming, à direita na foto, em visita ao Japão.

Caso de estudo: Transmissão Mazda-Ford

Nos anos 80, a Ford fez uma parceria com a Mazda para produzir câmbios automáticos para carros da Ford.

Ambas as companhias produziam essa transmissão e nas duas os produtos saíam de fábrica dentro das margens de tolerância. Contudo, transmissões Ford recebiam mais reclamações de clientes e tinham reparos mais caros; não só isso, as pessoas chegavam às concessionárias da Ford pedindo que seus carros novos viéssem com transmissão japonesa, pois eram mais macios de dirigir.

Os engenheiros da Ford investigaram e notaram que as transmissões Ford tinham variância de 70% da margem de tolerância, enquanto que as transmissões Mazda tinham variância de 27%. Por exemplo, se a especificação de uma peça era de 300mm ± 3mm, na Ford as peças variavam 2,1mm; na Mazda, 1,15mm.

O custo de produção na Mazda era um pouco mais caro, porém, o custo de arcar com a garantia na Ford era maior.

Após esse estudo, a fábrica da Ford melhorou a qualidade das suas transmissões, que se tornaram melhores do que as da Mazda.

Caso de estudo: TVs da Sony

Também nos anos 80, a Sony tinha duas plantas de produção de TVs, uma no Japão e outra em San Diego, Califórnia.

Um dos parâmetros de qualidade era a densidade de côr, com margem de tolerância entre 9 e 14. As TVs produzidas em San Diego todas estavam dentro da margem, enquanto que 1,3 em cada 1000 das produzidas no Japão estavam fora. Todavia, os consumidores preferiam as TVs japonesas, pois a imagem na tela era mais homogênea, devido a uma menor variância de densidade de côr.

Reconhecimento nos EUA

Ironicamente, as idéias de Deming caíram em desuso nos EUA após a guerra e não tiveram aceitação entre os executivos americanos, pois eles acreditavam que qualidade era um custo, e não um investimento.

Nas décadas seguintes, Deming estendeu seu trabalho para além da estatística, abordando como melhorar a eficiência e organização nas empresas, resumindo suas idéias nos chamados 14 pontos para gestão.

Em 1980, a NBC produziu um documentário comparando empresas americanas e japonesas. Um dos entrevistados foi Deming, que começou a receber propostas de trabalho após aparecer na TV. Uma das empresas que o contratou foi a Ford.

No início da década de 1980, a Ford registrava prejuízos de mais de 3 bilhões de dólares. Deming foi contratado e disse que a gerência era responsável por 85% dos problemas que impediam o desenvolvimento de carros melhores. Os executivos da Ford levaram isso a sério e adotaram as idéias de Deming: em 1986, a empresa se tornou a montadora americana com maior lucro, ultrapassando a General Motors pela primeira vez desde a década de 1920. O lucro cresceu consistentemente nos anos seguintes.

Linha de produção do Ford Taurus, em 1986. O modelo foi um sucesso de vendas e salvou a companhia da falência.

14 pontos para gestão

No livro Saia da Crise, Deming cita os seguintes pontos para a boa gestão de uma empresa:

Criar constância de propósito de aperfeiçoamento do produto e serviço, a fim de torná-los competitivos, perpetuá-los no mercado e gerar empregos.
Adotar a nova filosofia. Vivemos numa nova era econômica. Os executivos e gerentes ocidentais devem despertar para o desafio, conscientizar-se de suas responsabilidades e assumir a liderança em direção à transformação.
Acabar com a dependência de inspeção para a obtenção da qualidade. Eliminar a necessidade de inspeção em massa, focando em fazer certo desde o começo.
Acabar com a prática de escolher fornecedores apenas com base em preço. Em vez disso, minimizar o custo total. Preferir um único fornecedor para cada item, estabelecendo relacionamentos duradouros, calcados na qualidade e na confiança.
Aperfeiçoar constante e continuamente todo o processo de planejamento, produção e serviços, com o objetivo de aumentar a qualidade e a produtividade e, conseqüentemente, reduzir custos.
Fornecer treinamento no local de trabalho.
Instituir liderança. O objetivo da liderança é ajudar as pessoas e máquinas a realizar um trabalho melhor.
Eliminar o medo no local de trabalho.
Quebrar as barreiras entre departamentos. Os colaboradores dos setores de pesquisa, projetos, vendas, compras ou produção devem trabalhar em equipe, para antever problemas na produção ou nos produtos e serviços.
Eliminar slogans, exortações e pedidos para que a produtividade aumente e não ocorram erros. Tais exortações apenas instigam rivalidades entre as pessoas, sendo que o grosso das causas de baixa qualidade e produtividade está no sistema como um todo e não na força de trabalho.

a) Eliminar metas numéricas para o chão de fábrica.

b) Eliminar administração por objetivos — líderes devem conhecer o sistema e prover um plano de trabalho.
Remover barreiras que roubem das pessoas o sentimento de orgulho no trabalho. A atenção dos supervisores deve voltar-se para a qualidade e não para números.
Remover barreiras que roubam dos gerentes e engenheiros o justo direito de se orgulhar do produto de seu trabalho. Isso significa abolir avaliações anuais e de mérito, e da administração por objetivos ou números.
Instituir um programa vigoroso de educação e auto-aperfeiçoamento para todo o pessoal.
Empenhar todos na companhia para conseguir essa transformação. É um trabalho de todos.

Fontes e leituras interessantes

Collation e encoding em bancos de dados

2024-08-29T00:00:00Z

Introdução

Toda informação em um computador é armazenada e processada na sua representação em número binário.

Mas e os textos? Um texto é uma seqüência de caractéres, um caractér sendo uma letra ou um símbolo. Cada caractér é representado por um número binário, sendo que o mapeamento caractér-número é chamado de encoding.

A tabela abaixo é do encoding Windows-1252, que contempla 255 caractéres possíveis, cada um representado por um byte. Você pode ver essa tabela com o Mapa de Caractéres do Windows (Win+R, charmap).

A collation, por sua vez, é a regra de ordenação usada para comparar textos. Ela também determina qual é o encoding utilizado para armazenamento.

No Microsoft SQL Server, no nome de uma collation, CI / CS significa case (in)sensitive — diferenciação por maiúsculas e minúsculas; AI / AS, accent (in)sensitive — diferenciação por acentos. Com uma collation case-insensitive (CI), por exemplo, tanto faz pesquisar silva ou SILVA. Com uma collation accent-insensitive (AI), Acucar e Açúcar são considerados iguais em comparações.

Accent-insensitive na verdade é insensível para todos os diacríticos de um idioma, como cedilhas (ç, ş) e acentos (é, ã, ô, etc). Algumas collations mais antigas não cobrem todos os diacríticos nas comparações (link), por isso, collations mais novas são preferíveis.

SELECT
  [Name],
  COLLATIONPROPERTY( [Name], 'LCID' ) AS [LCID],
  COLLATIONPROPERTY( [Name], 'CodePage' ) AS [CodePage]
FROM sys.fn_helpcollations()
ORDER BY [Name];

Nome	Encoding	Compara casing	Compara acentos
Latin1_General_ CI_AS	Windows-1252	Não	Sim
Latin1_General_ 100_CI_AS_ KS_SC_UTF8	UTF-8 (65001)	Não	Sim
Latin1_General_ 100_CS_AS_ KS_SC_UTF8	UTF-8 (65001)	Sim	Sim

Unicode, UTF-8 e UTF-16

O Unicode é uma tabela que define um número para cada caractér, compreendendo símbolos, algarismos e letras de diversos alfabetos. O número atribuído a um caractér é chamado de code point.

O UTF-8 e o UTF-16 são encodings que seguem o Unicode. Basicamente, são formas de armazenar esses números em bytes.

O UTF-16 usa 2 bytes para a maioria dos caractéres e 4 para aqueles acima do intervalo padrão. Esse encoding é usado nas strings da maioria das linguagens de programação.

O UTF-8 usa uma quantidade variável de bytes, de 1 a 4 por caractér. É o principal encoding da Internet.

Intervalo Unicode	Grupos	Bytes por char, UTF-8	Bytes por char, UTF-16
0x0000 a 0x007F	Alfabeto latino básico, algarismos arábicos (0 a 9), símbolos básicos do teclado	1	2
0x0080 a 0x07FF	Alfabetos latino estendido (com acentos, cedilhas), grego, cirílico, árabe, hebraico	2	2
0x0800 a 0xFFFF	Ideogramas japoneses e chineses; símbolos variados; operadores matemáticos	3	2
0x010000 a 0x10FFFF	Pictogramas de escritas antigas (ex.: hieróglifos egípcios); emojis; símbolos musicais	4	4

A escolha do encoding afeta diretamente o tamanho usado para armazenamento de textos. Se a maioria dos caractéres estiver no intervalo de alfabeto latino básico, o UTF-8 é melhor, porque usa menos bytes do que o UTF-16; mas, se a escrita for asiática, o UTF-16 tem vantagem, pois o caractér ocupa 2 bytes, contra 3 do UTF-8.

A tabela abaixo mostra como um número Unicode é convertido para UTF-8 ou UTF-16, para cada intervalo acima.

Caractér de exemplo	Code point em binário	Em UTF-8	Em UTF-16
P (0x0050)	00110010	00110010	00000000 00110010
Ω (0x03A9)	00000011 10101001	11001110 10101001	00000011 10101001
€ (0x20AC)	00100000 10101100	11100010 10000010 10101100	00100000 10101100
🐎 (0x1F40E)	00000001 11110100 00001110	11110000 10011111 10010000 10001110	11011000 00111101 11011100 00001110

A lógica do UTF-16 para code points acima de 0x010000 é:

U = code point
W1 = 2 bytes superiores
W2 = 2 bytes inferiores

W = U - 0x10000 
W = yyyyyyyyyyxxxxxxxxxx (20 dígitos binários)
W1 = 110110yy yyyyyyyy
W2 = 110111xx xxxxxxxx

-> não há risco de W1 e W2 serem encarados como 
outros caracteres porque o intervalo possível deles 
é protegido na tabela Unicode.

Textos em bancos de dados SQL

CHAR e NCHAR recebem textos de tamanhos fixos; já o VARCHAR e o NVARCHAR aceitam tamanhos variáveis.

NCHAR e NVARCHAR são tipos presentes no SQL Server e o 'N' indica que eles armazenam o texto em codificação UTF-16. Já o CHAR e VARCHAR armazenam conforme o encoding da collation do banco.

Na declaração de tipo de coluna, é especificado o tamanho aceito por ela, por exemplo, NVARCHAR(n). É muito comum as pessoas pensarem que n é o tamanho em caractéres, mas isso não é verdade. Para CHAR e VARCHAR, n define o tamanho em bytes; para NCHAR e NVARCHAR, n é o tamanho em pares de bytes (x2).

Exemplo prático

Temos dois bancos de dados, um com collation Latin1_General_CI_AS (encoding Windows-1252) e outro com a collation Latin1_General_100_CI_AS_KS_SC_UTF8 (encoding UTF-8). Para cada um deles, vamos comparar o armazenamento entre VARCHAR e NVARCHAR, para textos em alfabeto latino básico, latino estendido, grego e emojis. Segue o script para executar:

CREATE TABLE [dbo].[Pessoa] (
  [Nome] VARCHAR(24) NOT NULL,
  [NomeUtf16] NVARCHAR(24) NOT NULL
);

INSERT INTO [dbo].[Pessoa] VALUES
('Pericles','Pericles'), -- latino sem acento
('Péricles','Péricles'), -- latino com acento
(N'Περικλῆς',N'Περικλῆς'), -- grego
(N'美しいキモノ',N'美しいキモノ'), -- japonês katakana
(N'Papai Noel 🎅',N'Papai Noel 🎅'); -- com emoji
-- o prefixo N é necessário para strings unicode

SELECT
  [Nome], DATALENGTH([Nome]) AS [TamanhoEmBytes],
  [NomeUtf16], DATALENGTH([NomeUtf16]) AS [TamanhoEmBytes]
FROM [dbo].[Pessoa];

DROP TABLE [dbo].[Pessoa];

Latin1 General CI AS

Nome VARCHAR	Tamanho em bytes	Nome NVARCHAR	Tamanho em bytes
Pericles	8	Pericles	16
Péricles	8	Péricles	16
?e??????	8	Περικλῆς	16
??????	6	美しいキモノ	12
Papai Noel ??	13	Papai Noel 🎅	26

Podemos perceber que o encoding Windows-1252 não suporta caractéres gregos, japoneses e emojis, que são substituídos por '?'. Apesar disso, consegue atender muito bem palavras latinas, gastando apenas 1 byte por letra, mesmo naquelas com acentos ou cedilhas.

Latin1 General 100 CI AS KS SC UTF8

Nome VARCHAR	Tamanho em bytes	Nome NVARCHAR	Tamanho em bytes
Pericles	8	Pericles	16
Péricles	9	Péricles	16
Περικλῆς	17	Περικλῆς	16
美しいキモノ	18	美しいキモノ	12
Papai Noel 🎅	15	Papai Noel 🎅	26

Com a collation UTF-8, o campo VARCHAR suportou com sucesso todos os caractéres e teve maior eficiência em geral. O terceiro nome, Περικλῆς, precisou de 17 bytes porque a letra ῆ (unicode 0x1FC6) é do grego antigo e requer 3 bytes em UTF-8. Para japonês katakana, UTF-16 provou-se mais eficiente.

Fontes e leituras interessantes

Iceberg SQL

2024-08-14T00:00:00Z

Introdução

A linguagem SQL, em inglês, Structured Query Language, surgiu pela primeira vez em 1974 e é uma das principais linguagens até hoje, em se tratando de bancos de dados.

O SQL evoluiu muito ao longo dos anos e principalmente nas duas últimas décadas, com novas técnicas de organização de dados, que surgiram diante de novos competidores (NoSQL) e novas necessidades (analytics, data warehouse, computação na nuvem).

Este artigo é uma lista de trapaças do SQL, abordando desde comandos comuns até aqueles raros e com aplicações muito interessantes. Procurei fazer aqui uma lista fácil de entender tanto para iniciantes como para quem já tem familiaridade com a linguagem.

Os exemplos aqui são em Microsoft SQL Server, porém, a maioria deles existe de forma igual ou semelhante em outros bancos de dados, como o PostgreSQL, MySQL e Oracle.

Antes de começar

Leituras e consultas

Alterações de dados

Formação de tabelas

Especiais

Conclusões finais

Antes de começar

Instalação

Para testar os exemplos do artigo, recomendo ter instalados o SQL Server (download) e o SQL Server Management Studio (SSMS) (download).

Após as instalações, entrar no SSMS e logar na sua instância:

Autenticação do Windows
Nome do servidor: . (ponto)
Marcar Certificado do Servidor Confiável

Essas opções podem mudar conforme a configuração durante a instalação.

Depois, escolher um banco de dados no painel esquerdo; se não houver um, clicar com o botão direito do mouse em Bancos de Dados e criar um.

Para escrever um script SQL, clicar em Nova Consulta, no menu superior. Para executar, apertar F5 ou clicar em Executar.

Tabelas de exemplo

Vamos começar com duas tabelas que vão servir de base para nossos exemplos: tabela Fruta e tabela Familia.

Tabela [dbo].[Fruta]:

Id	Nome	IdFamília	Calorias*
1	Côco	1	354
2	Tâmara	1	282
3	Morango	3	32
4	Melancia	2	30
5	Maracujá	4	97
6	Cereja	3	64
7	Abacaxi	5	48
8	Maçã	3	52

* Quantidade de calorias por 100g. Fonte: Mundo Boa Forma.

Tabela [dbo].[Familia]:

Id	Família
1	Arecaceae
2	Cucurbitaceae
3	Rosaceae
4	Passifloraceae
5	Bromeliaceae
6	Malvaceae

Para criá-las, executar o script SQL abaixo no seu banco.

CREATE TABLE [dbo].[Familia](
  [Id] INT NOT NULL IDENTITY(1,1) PRIMARY KEY CLUSTERED,
  [Nome] NVARCHAR(64) NOT NULL)
GO

INSERT INTO [dbo].[Familia] VALUES
  ('Arecaceae'), ('Cucurbitaceae'), ('Rosaceae'),
  ('Passifloraceae'), ('Bromeliaceae'), ('Malvaceae');
GO

CREATE TABLE [dbo].[Fruta](
  [Id] INT NOT NULL IDENTITY(1,1) PRIMARY KEY CLUSTERED,
  [Nome] NVARCHAR(64) NOT NULL,
  [IdFamilia] INT NOT NULL FOREIGN KEY REFERENCES [dbo].[Familia](Id),
  [Calorias] INT NOT NULL)
GO

INSERT INTO [dbo].[Fruta] VALUES 
  ('Côco', 1, 354), ('Tâmara', 1, 282), ('Morango', 3, 32),
  ('Melancia', 2, 30), ('Maracujá', 4, 97), ('Cereja', 3, 64),
  ('Abacaxi', 5, 48), ('Maçã', 3, 52);
GO

Leituras e consultas

SELECT

Obtém dados devolvendo em forma de tabela.

SELECT [Nome], [Calorias]
FROM [dbo].[Fruta]
WHERE [Calorias] < 50

Retorna:

Nome	Calorias
Morango	32
Melancia	30
Abacaxi	48

* significa retornar todas as colunas:

SELECT *
FROM [dbo].[Fruta]
WHERE [Calorias] < 50

Id	Nome	IdFamilia	Calorias
3	Morango	3	32
4	Melancia	2	30
7	Abacaxi	5	48

LEFT, RIGHT, INNER JOINS

Entrelaça duas ou mais tabelas com base em colunas de referência; esse entrelaçamento pode ser usado em consultas, inserções, alterações e exclusões.

Aqui vamos focar apenas no INNER JOIN e no LEFT JOIN.

INNER JOIN

O INNER JOIN é uma intersecção perfeita, ou seja, os valores de entrelaçamento devem existir em ambas as tabelas. Se existir em uma linha da tabela X, mas sem linha correspondente em outra tabela Y, a linha da tabela X não é considerada. Exemplo:

Tabela [dbo].[Fruta]:

Id	Nome	IdFamília	Calorias
3	Morango	3	32
4	Melancia	2	30
7	Abacaxi	5	48

Tabela [dbo].[Familia]:

Id	Família
2	Cucurbitaceae
3	Rosaceae
5	Bromeliaceae

Comando SQL:

SELECT
    fr.[Nome] AS [Nome],
    fa.[Nome] AS [Família]
FROM [dbo].[Fruta] fr
INNER JOIN [dbo].[Familia] fa ON fr.[IdFamilia] = fa.[Id]
WHERE fr.[Calorias] < 50

Retorna:

Nome	Família
Morango	Rosaceae
Melancia	Cucurbitaceae
Abacaxi	Bromeliaceae

LEFT / RIGHT JOIN

O LEFT JOIN e o RIGHT JOIN são intersecções imperfeitas, de modo que o valor de referência pode não existir em uma das tabelas; se não existir, então os valores vindos da tabela sem linha correspondente virão nulos.

Nas tabelas acima, a família Malvaceae (id = 6) não tem nenhuma fruta cadastrada.

SELECT
    fa.[Nome] AS [Família],
    fr.[Nome] AS [Fruta]
FROM [dbo].[Familia] fa
LEFT JOIN [dbo].[Fruta] fr ON fr.[IdFamilia] = fa.[Id]

Família	Fruta
Arecaceae	Côco
Arecaceae	Tâmara
Cucurbitaceae	Melancia
Rosaceae	Morango
Rosaceae	Cereja
Rosaceae	Maçã
Passifloraceae	Maracujá
Bromeliaceae	Abacaxi
Malvaceae	`NULL`

VIEWS

As VIEWS são consultas encapsuladas: ao invés de executar toda vez uma consulta SQL que é complexa, você pode "apelidar" essa consulta através de uma view, o que simplifica a chamada. Essa técnica é boa para abstrair lógica e para controlar permissões de acesso, por exemplo, um usuário pode chamar a view, mas ficar impedido de acessar as tabelas do banco.

Criação da view:

CREATE OR ALTER VIEW [dbo].[ViewObterFrutas] AS

  SELECT
    fr.[Nome] AS [Fruta],
    fa.[Nome] AS [Família]
  FROM [dbo].[Fruta] fr
  INNER JOIN [dbo].[Familia] fa ON fr.[IdFamilia] = fa.[Id]

GO

Para executá-la:

-- a view age como se fosse uma tabela
SELECT * FROM [dbo].[ViewObterFrutas]

GROUP BY, HAVING

O GROUP BY é uma instrução de agrupamento e o HAVING é um filtro que se aplica a grupos.

As colunas retornadas por um SELECT com agrupamento precisam estar especificadas no GROUP BY, ou então estarem em funções de agregação, como contagens, somas, médias, etc.

Exemplo:

SELECT fr.[IdFamilia], COUNT(fr.[Id]) AS QuantidadeDeFrutas
FROM [dbo].[Fruta] fr
GROUP BY fr.[IdFamilia]

IdFamília	QuantidadeDeFrutas
1	2
2	1
3	3
4	1
5	1

Com inner join e filtro sobre os grupos:

SELECT fa.[Nome] AS [Família], COUNT(fr.[Id]) AS QuantidadeDeFrutas
FROM [dbo].[Fruta] fr
INNER JOIN [dbo].[Familia] fa ON fr.[IdFamilia] = fa.[Id]
GROUP BY fa.[Nome]
HAVING COUNT(fr.[Id]) >= 2 -- família c/ 2 ou mais frutas

Família	QuantidadeDeFrutas
Arecaceae	2
Rosaceae	3

UNION, INTERSECT, EXCEPT

São operadores de conjuntos (ver teoria dos conjuntos na matemática). São diferentes do entrelaçamento que acontece nos JOINS — enquanto que nos JOINS o entrelaçamento é com colunas, nos conjuntos o entrelaçamento é com linhas. Os exemplos abaixo mostram visualmente.

UNION: Retorna elementos que pertencem a um conjunto ou outro.
INTERSECT: Retorna elementos que pertencem a um conjunto e a outro, ao mesmo tempo.
EXCEPT: Retorna elementos que pertencem a um conjunto, mas não a outro.

DECLARE @a TABLE (X INT);
INSERT INTO @a VALUES (1),(2),(3),(4),(5);

DECLARE @b TABLE (X INT);
INSERT INTO @b VALUES (2),(4),(6);

SELECT * FROM @a

UNION -- INTERSECT, EXCEPT

SELECT * FROM @b

A	B	UNION	INTERSECT	EXCEPT
1	2	1	2	1
2	4	2	4	3
3	6	3	-	5
4	-	4	-	-
5	-	5	-	-
-	-	6	-	-

Por que usar um UNION se posso simplesmente escrever WHERE critério1 OR critério2 ?

Às vezes queremos unir linhas vindas de tabelas diferentes:

SELECT * FROM Tabela1 WHERE criterio
UNION
SELECT * FROM Tabela2 WHERE criterio

O que é UNION ALL?

Na teoria dos conjuntos, um conjunto nunca tem elementos repetidos. Porém, nas consultas em SQL, às vezes queremos que uma união permita duplicações, para isso, usamos UNION ALL ao invés de só UNION.

SUBQUERIES

São consultas que ocorrem dentro de outras. Podem ser úteis em algumas operações mais complexas, porém, sempre que possível, é melhor substituir uma subquery por um join, pois este tem execução mais rápida.

No exemplo abaixo, o nome da família da fruta é obtido através de subquery:

SELECT
    fr.[Nome] AS [Nome],
    (SELECT fa.[Nome] FROM [dbo].[Familia] fa WHERE fa.[Id] = fr.[IdFamilia]) AS [Família]
FROM [dbo].[Fruta] fr
WHERE fr.[Calorias] < 50

SELF JOIN

É um join de uma tabela consigo mesma. Muito usado para operações em árvores.

Abaixo, temos uma tabela Funcionários, sendo que um funcionário pode ser chefe de outros:

DECLARE @funcionarios TABLE (Id INT, Nome NVARCHAR(32), IdChefe INT);
INSERT INTO @funcionarios VALUES
(1, 'Marco', 4),
(2, 'Antônio', NULL),
(3, 'Fernando', 2),
(4, 'Luciana', 2),
(5, 'Fabiana', 4);

SELECT
  f1.[Nome] AS [Funcionário],
  f2.[Nome] AS [SubordinadoA]
FROM @funcionarios f1
LEFT JOIN @funcionarios f2 ON f1.[IdChefe] = f2.[Id]
ORDER BY f2.[Id] ASC

Funcionário	SubordinadoA
Antônio	`NULL`
Fernando	Antônio
Luciana	Antônio
Fabiana	Luciana
Marco	Luciana

CROSS JOIN

É o produto cartesiano entre tabelas, basicamente, faz todas as combinações possíveis dos elementos de uma com a outra.

Considere duas tabelas, Sorvete e Cobertura, e queremos ver quais são as combinações.

DECLARE @sorvete TABLE (Id INT, Nome NVARCHAR(32));
INSERT INTO @sorvete VALUES
(1, 'Morango'), (2, 'Flocos'), (3, 'Chocolate');

DECLARE @cobertura TABLE (Id INT, Nome NVARCHAR(32));
INSERT INTO @cobertura VALUES
(1, 'Calda de chocolate'), (2, 'Nozes');

SELECT s.[Nome] AS Sorvete, c.[Nome] AS Cobertura
FROM @sorvete s CROSS JOIN @cobertura c
ORDER BY s.[Id] ASC, c.[Id] ASC

Sorvete	Cobertura
Morango	Calda de chocolate
Morango	Nozes
Flocos	Calda de chocolate
Flocos	Nozes
Chocolate	Calda de chocolate
Chocolate	Nozes

PIVOT

A instrução PIVOT é muito interessante. Ela transforma linhas em colunas, ou seja, rotaciona em 90º uma parte da tabela. Ela é muito boa para cruzar duas ou mais colunas de uma mesma tabela.

No exemplo abaixo, temos uma tabela Vendas em que cada linha dela é a quantidade de um produto vendida em um determinado dia. Queremos ver esses dados de uma forma mais clara, transformando as datas de vendas em colunas, e para isso, usaremos o PIVOT.

DECLARE @vendas TABLE (IdProduto INT, Quantidade INT, DataVenda DATE);
INSERT INTO @vendas VALUES
(5, 52, '2024-08-05'),
(3, 902, '2024-08-05'),
(1, 196, '2024-08-06'),
(4, 212, '2024-08-06'),
(3, 488, '2024-08-07'),
(4, 384, '2024-08-07'),
(1, 1121, '2024-08-08'),
(2, 49, '2024-08-08'),
(3, 88, '2024-08-09'),
(2, 12, '2024-08-09'),
(5, 98, '2024-08-09');

SELECT * FROM
(
  SELECT [DataVenda], [IdProduto], [Quantidade]
  FROM @vendas
) t
PIVOT(
  SUM([Quantidade]) FOR [DataVenda] IN ([2024-08-05],[2024-08-06],[2024-08-07],[2024-08-08],[2024-08-09])
) AS pvt;

IdProduto	2024-08-05	2024-08-06	2024-08-07	2024-08-08	2024-08-09
1	NULL	196	NULL	1121	NULL
2	NULL	NULL	NULL	49	12
3	902	NULL	488	NULL	88
4	NULL	212	384	NULL	NULL
5	52	NULL	NULL	NULL	98

E se eu quiser gerar as colunas dinamicamente, sem especificar valores fixos para elas?

Você pode gerar dinamicamente o texto do comando SQL e então rodá-lo. Este artigo mostra como fazer isso dentro de uma procedure:

CREATE PROCEDURE dbo.GerarBoletinsAlunos
  @ColunaParaPivotar  NVARCHAR(255),
  @ListaParaPivotar   NVARCHAR(255)
AS
BEGIN
 
  DECLARE @SqlStatement NVARCHAR(MAX)
  SET @SqlStatement = N'
    SELECT * FROM (
      SELECT [Estudante], [Matéria], [NotaProva]
      FROM [Notas]
    ) x
    PIVOT (
      AVG([NotaProva]) -- média das provas
      FOR ['+@ColunaParaPivotar+']
      IN ('+@ListaParaPivotar+')
    ) AS pvt'; 
  EXEC(@SqlStatement)
 
END

Para executar:

EXEC dbo.GerarBoletinsAlunos
  N'Matéria',
  N'[Português],[Matemática],[Ciências]'

ROLLUP, CUBE, GROUPING SETS

São tipos de GROUP BY que analisam também os subgrupos possíveis.

DECLARE @vendas TABLE (IdProduto INT, Quantidade INT, DataVenda DATE);
INSERT INTO @vendas VALUES
(5, 52, '2024-08-05'),
(3, 902, '2024-08-05'),
(1, 196, '2024-08-06'),
(4, 212, '2024-08-06'),
(3, 488, '2024-08-07'),
(4, 384, '2024-08-07');

SELECT [DataVenda], [IdProduto], SUM([Quantidade]) AS [Quantidade]
FROM @vendas
GROUP BY ROLLUP([DataVenda],[IdProduto]) -- CUBE, GROUPING SETS

ROLLUP

Monta subgrupos em pirâmide, da direita para a esquerda na declaração. Ex.: GROUP BY ROLLUP([ColA], [ColB]) vai analisar:

[ColA], [ColB] (subgrupo de A e B)
[ColA], NULL (subgrupo de A para todos os valores de B)
NULL, NULL (grupo geral)

DataVenda	IdProduto	Quantidade
2024-08-05	3	902
2024-08-05	5	52
2024-08-05	NULL	954
2024-08-06	1	196
2024-08-06	4	212
2024-08-06	NULL	408
2024-08-07	3	488
2024-08-07	4	384
2024-08-07	NULL	872
NULL	NULL	2234

CUBE

Monta todos os subgrupos possíveis. Ex.: GROUP BY CUBE([ColA], [ColB]) gerará:

[ColA], [ColB] (subgrupo de A e B)
[ColA], NULL (subgrupo de A para todos os valores de B)
NULL, [ColB] (subgrupo de B para todos os valores de A)
NULL, NULL (grupo geral)

DataVenda	IdProduto	Quantidade
2024-08-06	1	196
NULL	1	196
2024-08-05	3	902
2024-08-07	3	488
NULL	3	1390
2024-08-06	4	212
2024-08-07	4	384
NULL	4	596
2024-08-05	5	52
NULL	5	52
NULL	NULL	2234
2024-08-05	NULL	954
2024-08-06	NULL	408
2024-08-07	NULL	872

GROUPING SETS

Junta os subgrupos possíveis de cada coluna em análise, mas não cruza colunas entre si. Ex.: GROUP BY GROUPING SETS([ColA], [ColB]) produz:

[ColA], NULL (subgrupo de A para todos os valores de B)
NULL, [ColB] (subgrupo de B para todos os valores de A)

DataVenda	IdProduto	Quantidade
NULL	1	196
NULL	3	1390
NULL	4	596
NULL	5	52
2024-08-05	NULL	954
2024-08-06	NULL	408
2024-08-07	NULL	872

WINDOW FUNCTION

São funções que atribuem valores olhando para fatias (ou janelas) da tabela. São muito úteis para fazer paginação, por exemplo, em pesquisas de produtos.

É um tema extenso e com várias possibilidades, por isso, não vou entrar em detalhes aqui, contudo, recomendo este artigo que explica muito bem como as window functions funcionam.

NOLOCK

NOLOCK, ou READ UNCOMMITTED, é um modo de leitura que, como o nome sugere, ignora locks.

Uma consulta normal usa o nível de isolamento padrão, READ COMMITTED, que lê apenas dados commitados na tabela. Em uma tabela com tráfego intenso (muitas operações simultâneas), uma consulta pode enfrentar problemas de concorrência com inserts, updates e deletes.

Com a opção NOLOCK, a leitura não compete com essas operações. Porém, esse tipo de leitura inclui registros não-commitados, tal que dados inconsistentes podem aparecer nos resultados. De forma geral, NOLOCK deve ser usado apenas se houver de fato um problema de concorrência, e se eventuais inconsistências forem toleráveis. Um exemplo de uso é a extração de relatórios analíticos.

SELECT *
FROM [dbo].[Fruta] WITH (NOLOCK)
WHERE [Calorias] < 50

Alterações de dados

INSERT, UPDATE, DELETE

Adiciona, modifica e exclui registros em uma tabela.

DECLARE @pessoas TABLE (Id INT, Nome NVARCHAR(32));

-- inserindo com VALUES
INSERT INTO @pessoas VALUES
(1, 'Cláudio'), (2, 'Carolina');

-- inserindo com SELECT
INSERT INTO @pessoas SELECT 3, 'Josias';

-- alterando nome
UPDATE @pessoas
SET [Nome] = 'Cláudia'
WHERE [Id] = 1;

-- excluindo pessoa
DELETE FROM @pessoas
WHERE [Nome] = 'Josias';

-- resultado final
SELECT * FROM @pessoas

STORED PROCEDURES

São scripts que aceitam parâmetros e executam ações no banco de dados; podem devolver resultados em tabela e retornar valores.

A procedure abaixo pode ser usada para cadastrar frutas (considerando exemplo do início).

CREATE OR ALTER PROCEDURE [dbo].[ProcCadastrarFruta]
  @fruta NVARCHAR(32),
  @familia NVARCHAR(32),
  @calorias INT
AS
BEGIN

  -- verifica se fruta já está cadastrada
  IF EXISTS (SELECT 1 FROM [dbo].[Fruta] WHERE [Nome] = @fruta)
  BEGIN
    RAISERROR('Fruta já cadastrada!', 16, 1)
    RETURN 1; -- interromper execução
  END

  -- cadastra família se não existir
  IF NOT EXISTS (SELECT 1 FROM [dbo].[Familia] WHERE [Nome] = @familia)
  BEGIN
    INSERT INTO [dbo].[Familia] VALUES (@familia);
  END

  -- pega o id da família
  DECLARE @idFamilia INT = (SELECT [Id] FROM [dbo].[Familia] WHERE [Nome] = @familia)

  -- cadastra a fruta
  INSERT INTO [dbo].[Fruta] VALUES (@fruta, @idFamilia, @calorias);

  RETURN 0; -- tudo certo

END
GO

Para executar:

EXECUTE [dbo].[ProcCadastrarFruta]
  @fruta = 'Laranja',
  @familia = 'Rutaceae',
  @calorias = 37

MERGE

Permite executar simultaneamente inserções, modificações e exclusões, comparando uma tabela de origem com outra de destino. Essa instrução é usada para sincronização entre fontes de dados diferentes. Se as sincronizações são sempre INSERTS, ou sempre UPDATES, usar estas operações específicas resulta em performance melhor.

Também não vou entrar em detalhes aqui, porém, recomendo este artigo para quem interessar.

MERGE target_table USING source_table
ON merge_condition
WHEN MATCHED THEN update_statement
WHEN NOT MATCHED THEN insert_statement
WHEN NOT MATCHED BY SOURCE THEN DELETE;

BULK INSERT

O BULK INSERT é uma inserção em massa de dados vindos de um arquivo, geralmente em formato CSV, XML ou então arquivo posicional (flat file).

Essa é uma estratégia para mover uma grande quantidade de registros de um lugar para outro, principalmente se forem usados arquivos posicionais, pois eles são muito "sucintos" e têm altas taxas de compressão quando zipados (exemplo: um arquivo posicional de 900MB, quando zipado, pode ser reduzido a 30MB, dependendo do caso).

Considere o arquivo posicional a seguir. Repare que as posições de início de cada campo são sempre as mesmas — nome da fruta (0..16), nome da família (16..32), calorias (32..35):

Graviola        Annonaceae      66 
Mamão Papaya    Caricaceae      46 
Cambucá         Myrtaceae       66 
Bacuri          Clusiaceae      105
Cupuaçu         Malvaceae       49

Para importar um arquivo com BULK INSERT, recomendo 1) usar um arquivo formatador e 2) inserir primeiro em uma tabela intermediária, pois muitas vezes precisamos polir os dados antes de passar para a tabela final, por exemplo, remover espaços em branco ou converter datas. O arquivo a seguir é um format file em XML.

<?xml version="1.0"?>
<BCPFORMAT xmlns="http://schemas.microsoft.com/sqlserver/2004/bulkload/format" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<RECORD>
		<FIELD ID="F1" xsi:type="CharFixed" LENGTH="16"/><!-- Nome da fruta -->
		<FIELD ID="F2" xsi:type="CharFixed" LENGTH="16"/><!-- Nome da família -->
		<FIELD ID="F3" xsi:type="CharFixed" LENGTH="3"/><!-- Calorias -->
		<FIELD ID="F4" xsi:type="CharTerm" TERMINATOR="\r\n" MAX_LENGTH="6"/><!-- Fim de linha -->
	</RECORD>
	<ROW>
		<COLUMN SOURCE="F1" NAME="NomeFruta" xsi:type="SQLVARYCHAR" LENGTH="16" NULLABLE="NO"/>
		<COLUMN SOURCE="F2" NAME="NomeFamilia" xsi:type="SQLVARYCHAR" LENGTH="16" NULLABLE="NO"/>
		<COLUMN SOURCE="F3" NAME="Calorias" xsi:type="SQLINT"/>
	</ROW>
</BCPFORMAT>

Para executar um BULK INSERT em SQL:

-- tabela temporária
CREATE TABLE #entrada
(Fruta NVARCHAR(16), Família NVARCHAR(16), Calorias INT);

BULK INSERT #entrada 
FROM 'C:\MinhaPasta\arquivo_posicional.txt' 
WITH 
(
  CODEPAGE = '65001', -- codificação UTF-8 com BOM
  FORMATFILE = 'C:\MinhaPasta\arquivo_formatador.xml', 
  BATCHSIZE = 4000
);

-- polimento (remover espaços em branco)
UPDATE #entrada
SET [Fruta] = TRIM([Fruta]),
    [Família] = TRIM([Família])

SELECT * FROM #entrada

DROP TABLE #entrada

Confira mais nas documentações oficiais:

Exportando arquivos posicionais

Infelizmente, não existem maneiras práticas de se gerar arquivos diretamente do banco; no caso do SQL Server, há apenas o Import / Export Wizard, que é uma interface gráfica dentro do SSMS.

Todavia, é possível criar um programa que lê linhas do banco de dados e gera um arquivo posicional a partir delas; pode ser um programa console simples.

Formação de tabelas

PRIMARY KEY, FOREIGN KEY

A chave primária é um identificador exclusivo para cada linha da tabela e determina qual é a principal coluna de pesquisa, estruturando a tabela em uma árvore B; isto torna a leitura muito mais rápida.

Uma chave estrangeira é uma ligação entre a coluna de uma tabela com a chave primária de outra. Isso aumenta a performance dos JOINs entre essas tabelas e serve como validação de entradas, pois um valor só é válido se estiver cadastrado na tabela estrangeira.

Retomando o exemplo do início:

CREATE TABLE [dbo].[Fruta](
  [Id] INT NOT NULL IDENTITY(1,1) PRIMARY KEY CLUSTERED,
  [Nome] NVARCHAR(64) NOT NULL,
  [IdFamilia] INT NOT NULL FOREIGN KEY REFERENCES [dbo].[Familia](Id),
  [Calorias] INT NOT NULL)

INDEXES

São trilhas adicionais de pesquisa em uma tabela que servem para percorrer ela, em paralelo à chave primária. São úteis em tabelas que terão mais de um critério de busca.

Imagine uma tabela Pessoa, com as colunas Id, CPF e Nome: é comum querermos pesquisar uma pessoa pelo CPF ou pelo nome, porém, essas colunas não são a chave primária, o que torna a pesquisa através desses campos mais lenta. Nesses casos, a pesquisa é feita individualmente registro por registro, na tabela inteira; além disso, é uma comparação textual, e não numérica, porque CPF e nome são textos. Comparações textuais são mais lentas do que as numéricas, como é o caso do Id.

Para melhorar a velocidade de pesquisa, criamos índices. O tipo mais comum de índice é o hash index, que atribui um número aleatório para cada valor indexado e salva esse número junto à tabela. Sempre que houver uma pesquisa com esse critério, a comparação será numérica e com performance melhor do que verificar cada linha e campo individualmente.

Criação de índice:

-- uma coluna
CREATE INDEX IX_Pessoa_CPF ON [dbo].[Pessoa]([CPF]);

-- mais de uma coluna
CREATE INDEX IX_Endereco_CidadeEstadoPais
ON [dbo].[Endereco]([Cidade],[Estado],[País]);

UNIQUE

É um tipo especial de constraint que impede valores repetidos em uma coluna. Na maioria dos bancos de dados, criar uma unique constraint também cria um índice para essa coluna.

CREATE TABLE [dbo].[Pessoa] (  
  Id INT NOT NULL PRIMARY KEY CLUSTERED,
  CPF CHAR(11) NOT NULL,
  Nome NVARCHAR(64) NOT NULL,
  CONSTRAINT CT_Unique_Pessoa_CPF UNIQUE([CPF])
);

SPARSE

É um modificador de coluna que otimiza o armazenamento quando há muitos valores nulos.

No armazenamento tradicional, um campo tem um tamanho reservado para ele na linha mesmo quando o valor é nulo, acarretando em desperdício.

Usando colunas esparsas, um campo com valor nulo ocupa zero bytes na linha e campos não-nulos ocupam o tamanho original acrescido de 4 bytes.

Exemplo prático, coluna NVARCHAR(16) precisa de 32 bytes. Com sparse, se o valor for nulo, ocupará 0 bytes; se for não-nulo, ocupará 36 bytes.

Percentagem de nulos	Diferença de tamanho da coluna com SPARSE
0%	+12,5%
25%	-15,6%
75%	-71,9%

Fórmula matemática: 1 - ((T+4)/T) * (1-N)

T : tamanho original do campo
N : percentagem de nulos

Se praticamente não houver nulos, não há vantagem em usar colunas esparsas, mas elas economizam armazenamento se a taxa de nulabilidade for média ou alta.

CREATE TABLE [dbo].[Pessoa] (  
  Id INT NOT NULL PRIMARY KEY CLUSTERED,
  CPF CHAR(11) NOT NULL,
  Nome NVARCHAR(64) NOT NULL,
  CorPreferida NVARCHAR(32) SPARSE NULL);

COLUMNSTORE

Columnstore é uma estratégia de armazenamento.

O modo padrão de armazenamento de uma tabela é linear, por linhas, que ficam dentro de páginas. A, B e C são colunas:

flowchart TB
  subgraph page[Página]
    direction LR
    subgraph row1[Linha 1]
      direction TB
      A1
      B1
      C1
    end
    subgraph row2[Linha 2]
      direction TB
      A2
      B2
      C2
    end    
    subgraph row3[Linha 3]
      direction TB
      A3
      B3
      C3
    end
end

No armazenamento colunar, uma página é exclusiva de uma coluna:

flowchart TB
  subgraph pageC[Página]
    subgraph columnC[Coluna C]
      direction LR
      C1
      C2
      C3
    end
  end
  subgraph pageB[Página]
    subgraph columnB[Coluna B]
      direction LR
      B1
      B2
      B3
    end
  end  
  subgraph pageA[Página]
    subgraph columnA[Coluna A]
      direction LR
      A1
      A2
      A3
    end
  end

Qual é a vantagem dessa abordagem? O armazenamento colunar tem compressão por padrão, e se os valores se repetem muito nas colunas, consegue-se reduzir o tamanho de armazenamento.

Veja a seguir como funciona a compressão colunar:

Coluna sem compressão	Coluna com compressão
A	5 x A
A	2 x B
A	3 x A
A
A
B
B
A
A
A

Segundo a documentação do SQL Server, o tamanho de armazenamento pode ser até 10x menor e a velocidade de leitura 10x maior, comparado a um armazenamento linear.

Quando usar columnstore

Alto número de repetições de valores na direção vertical.
Baixa cardinalidade (variações possíveis de valores).
Volume grande de dados (mais de 500 mil linhas).
Cargas analíticas: somas, médias, contagens.

Quando não usar columnstore

Registros que sofrem muitas atualizações e exclusões, pois a compactação é desfeita quando há mudanças.
Registros que são entidades, pois tabelas columnstore não têm chave primária.
Contra-indicado se precisar de muitos JOINs com essa tabela.

Clusterizado vs não-clusterizado

Um índice columnstore clusterizado é quando a tabela usa armazenamento colunar. Um índice columnstore não-clusterizado é quando a tabela usa armazenamento linear e o columnstore é um índice auxiliar, paralelo; essa é uma opção quando se quer os benefícios do columnstore (performance em cargas analíticas) sem perder as propriedades de uma tabela linear (chaves primárias).

Comando SQL

CREATE TABLE [dbo].[EntradaArquivoFruta](
	Fruta NVARCHAR(16) NOT NULL,
	Família NVARCHAR(16) NOT NULL,
	Calorias INT NOT NULL,
	INDEX CCI_EntradaArquivoFruta CLUSTERED COLUMNSTORE);

Especiais

IMPORT DLLs

Sim, é possível importar DLLs para executar no SQL Server.

DLLs customizadas podem ser interessantes no SQL para casos em que não há funcionalidade nativa, como: ler e escrever arquivos no sistema; efetuar chamadas HTTP; gerar e validar hashes.

As DLLs precisam estar em .NET Framework e serem assinadas com um strong name.

O processo é um pouco complexo e me baseei neste artigo do C-Sharp Corner. Seguem os passos:

Criar um projeto Class Library em .NET Framework
Exemplo de código C# abaixo:

using System;

namespace MinhaLibDotnetSql
{
    public static class Class1
    {
        public static double CalcularHipotenusa(double cateto1, double cateto2) =>
            Math.Sqrt(Math.Pow(cateto1, 2) + Math.Pow(cateto2, 2));
    }
}

No Visual Studio, clicar com o botão direito do mouse no projeto, Propriedades, Assinatura, marcar Assinar o assembly. Escolher ou gerar um arquivo de chave de nome forte. Se for criar, pode desmarcar Proteger o arquivo de chaves com senha.
Compilar o projeto.
Agora, precisamos importar a chave assimétrica de assinatura, criar um login no banco master e conceder permissão de UNSAFE ASSEMBLY para ele:

USE [master]
GO

CREATE ASYMMETRIC KEY ChaveAssimetrica1
FROM EXECUTABLE FILE = 'C:\Projetos\MinhaLibDotnetSql\bin\Debug\MinhaLibDotnetSql.dll';
GO

CREATE LOGIN LoginChaveAssimetrica1
FROM ASYMMETRIC KEY ChaveAssimetrica1;
GO

GRANT UNSAFE ASSEMBLY TO LoginChaveAssimetrica1;
GO

No seu banco de dados de aplicação, criar um usuário para o login anterior, importar o assembly e habilitar a execução de código CLR:

USE [SeuBancoDB];
GO

CREATE USER UserLoginChaveAssimetrica1
FOR LOGIN LoginChaveAssimetrica1;
GO

CREATE ASSEMBLY AssemblyMinhaLib
FROM 'C:\Projetos\MinhaLibDotnetSql\bin\Debug\MinhaLibDotnetSql.dll'
WITH PERMISSION_SET = SAFE;
GO

sp_configure 'clr enabled', 1;
GO
RECONFIGURE;
GO

Vamos agora criar uma FUNCTION que executa o código da DLL:

USE [SeuBancoDB];
GO

-- para string, usar parâmetro NVARCHAR
CREATE FUNCTION [dbo].[CalcularHipotenusa] (@cateto1 FLOAT, @cateto2 FLOAT)
RETURNS FLOAT
AS
  EXTERNAL NAME [AssemblyMinhaLib].[MinhaLibDotnetSql.Class1].[CalcularHipotenusa];
GO

Para executar a função:

-- retorna 5
SELECT [dbo].[CalcularHipotenusa] (3.0, 4.0) as [Hipotenusa];

-- retorna 13
SELECT [dbo].[CalcularHipotenusa] (5.0, 12.0) as [Hipotenusa];

JSON

Para lidar com JSONs no banco de dados.

DECLARE @json NVARCHAR(100) =
'{"cidades": ["Aracaju", "João Pessoa", "Maceió"]}';

-- retorna 3 linhas com as cidades
SELECT * FROM OPENJSON(@json, '$.cidades')

-- retorna uma linha com a cidade escolhida
SELECT JSON_VALUE(@json, '$.cidades[1]')

Ver mais na documentação completa.

APPLOCKS

São trancas de aplicação dentro do banco de dados. São diferentes de locks em linhas de uma tabela.

Podem ser usadas para controle de concorrência, por exemplo, para leitura de mensagens com múltiplos consumidores simultâneos.

As funções no SQL Server são sp_getapplock e sp_releaseapplock.

Confira mais no artigo sobre arquitetura assíncrona sem filas.

VIEW EXECUTION PLAN

O plano de execução detalha quais são as etapas que o banco de dados precisa percorrer para executar um comando ou uma consulta.

No SSMS, basta habilitar a opção Incluir plano de execução no menu superior para que o plano seja exibido junto com os resultados.

Ao analisar o custo de cada etapa, você pode entender quais são os gargalos de performance e a partir daí implementar melhorias, tais como criar índices, refazer os critérios de WHERE e JOIN nas consultas, entre outras.

Conclusões finais

O SQL é uma ferramenta extremamente poderosa e completa, e adquiriu novas capacidades ao longo dos anos. Não é à toa que é o mainstream de banco de dados até hoje — ele é a base de desenvolvimento de sistemas complexos.

Esse artigo cobriu funções comuns e desconhecidas do SQL, e ainda assim existem inúmeras outras que poderiam ser abordadas aqui e com aplicações na vida real, por isso, vale a pena "fuçar" a documentação do seu banco de dados, pois muitas vezes ela tem a resposta para o desafio que você tem.

Shiki e Mermaid no 11ty

2024-07-16T00:00:00Z

11ty, Shiki e Mermaid

O 11ty (Eleventy) é um gerador de sites estáticos que usa templates. Ele tem uma pipeline de execução que torna fácil adicionar plug-ins e transformações a arquivos HTML, JS e CSS.

O Shiki é um pacote npm que renderiza blocos de código HTML com coloração de sintaxe de acordo com a linguagem do código. Dentre suas vantagens, ele permite temas duais (que alternam entre claro e escuro), notações de código com diferenças e foco, e temas customizados.

Neste post, vamos ver como integrar o Shiki e diagramas Mermaid em um projeto 11ty.

Integrando com o Shiki

Adicionar o Shiki ao projeto

npm install -D shiki

Plug-in para o Shiki

Criar um arquivo Javascript para configuração do Shiki no seu projeto, por exemplo, no caminho ./shiki.config.mjs (vamos fazer usando ES Modules). O highlighter deve ser usado preferencialmente como um singleton.

import { createHighlighter } from "shiki";

export default function (eleventyConfig, options) {
  // empty call to notify 11ty that we use this feature
  // eslint-disable-next-line no-empty-function
  eleventyConfig.amendLibrary('md', () => { });

  eleventyConfig.on('eleventy.before', async () => {

    const highlighter = await createHighlighter(
    {
      themes: ["light-plus", "dark-plus"],
      langs: ['html', 'sql', 'xml', 'javascript']
    });

    eleventyConfig.amendLibrary('md', (mdLib) =>
      mdLib.set({
        highlight: (code, lang) => {
          return highlighter.codeToHtml(code,
          {
            lang: lang,
            themes: {
              light: "light-plus",
              dark: "dark-plus"
            }
          });
        }
      })
    );
  });
};

Chamar plug-in do Shiki no `eleventy.config.mjs`

import shikiPlugin from "./shiki.config.mjs"; 

export default function (eleventyConfig) {
  // ...
  // substituir plug-in de syntax highlight padrão do 11ty
  eleventyConfig.addPlugin(syntaxHighlight) 
  eleventyConfig.addPlugin(shikiPlugin); 
  // ...
}

Integrando com o Mermaid

Se você quer usar o Shiki e também quer ter diagramas Mermaid, é necessário alterar o plug-in do Shiki para renderizar blocos Mermaid como divs HTML, ao invés de blocos de código.

Adicionar o htmlencode ao projeto

npm install -D htmlencode

Modificar o plug-in do Shiki

import { createHighlighter } from "shiki";
import htmlencode from "htmlencode"; 

export default function (eleventyConfig, options) {
  // empty call to notify 11ty that we use this feature
  // eslint-disable-next-line no-empty-function
  eleventyConfig.amendLibrary('md', () => { });

  eleventyConfig.on('eleventy.before', async () => {

    const highlighter = await createHighlighter(
    {
      themes: ["light-plus", "dark-plus"],
      langs: ['html', 'sql', 'xml', 'javascript']
    });

    eleventyConfig.amendLibrary('md', (mdLib) =>
      mdLib.set({
        highlight: (code, lang) => {
          if (lang === "mermaid") { 
            const extra_classes = options?.extra_classes ? ' ' + options.extra_classes : ''; 
            return `<div class="mermaid${extra_classes}">${htmlencode.htmlEncode(code)}</div>`; 
          } 
          else { 
            return highlighter.codeToHtml(code,
            {
              lang: lang,
              themes: {
                light: "light-plus",
                dark: "dark-plus"
              }
            });
          } 
        }
      })
    );
  });
};

Plug-in para o Mermaid

Criar um arquivo Javascript para configuração do Mermaid no seu projeto, por exemplo, no caminho ./mermaid.config.mjs (vamos fazer usando ES Modules):

export default (eleventyConfig, options) => {
  let mermaid_config = {
    startOnLoad: false,
    theme: "default",
    loadOnSave: true
  };
  let src = options?.mermaid_js_src || "https://unpkg.com/mermaid/dist/mermaid.esm.min.mjs";

  eleventyConfig.addShortcode("mermaid_js_scripts", () => {
    return `<script type="module" async>
              import mermaid from "${src}";
              const config = ${JSON.stringify(mermaid_config)};
              mermaid.initialize(config);
              await mermaid.run({
                querySelector: '.mermaid'
              });
            </script>`
  });
  return {}
};

Chamar plug-in do Mermaid no `eleventy.config.mjs`

import shikiPlugin from "./shiki.config.mjs";
import mermaidPlugin from "./mermaid.config.mjs"; 

export default function (eleventyConfig) {
  // ...
  eleventyConfig.addPlugin(shikiPlugin);
  eleventyConfig.addPlugin(mermaidPlugin); 
  // ...
}

Incluir script do Mermaid nas páginas

Adicionar o shortcode mermaid_js_scripts nas páginas e templates que vão ter diagramas:

{% mermaid_js_scripts %}

Resultados finais

Vamos ver funcionando.

Bloco de código SQL com coloração de sintaxe:

SELECT * INTO dbo.NewProducts
FROM Production.Product
WHERE ListPrice > 25
AND ListPrice < 100;

Diagrama de fluxo do Mermaid:

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

Se quiser conferir um exemplo completo de código para este blog, visite nosso repo no GitHub. Lá você encontra como alternar entre tema claro e escuro, tanto para o Shiki como para o Mermaid.

Botões para copiar código

O Shiki não provê de fábrica botões para copiar código, porém, podemos adicioná-los através de um script do lado do cliente. Aqui, usaremos uma versão modificada do exemplo deste post de blog.

Referenciar o script nos templates

Adicionar a tag <script> abaixo nos templates e arquivos HTML:

<script src="/assets/scripts/addCopyCodeButtons.js"></script>

Script para adicionar botões de copiar código

Vamos criar um script de lado de cliente que vai pegar todos os blocos de código e inserir botões de copiar neles. Os ícones estão declarados em linha neste exemplo, como SVGs.

Exemplo de arquivo no caminho src/scripts/addCopyCodeButtons.js:

let blocks = document.querySelectorAll("pre.shiki");
const copyCodeIconSvg = '<svg height="16" viewBox="0 0 16 16" version="1.1" width="16"><path fill="#666666" d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path fill="#666666" d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg>';
const codeCopiedIconSvg = '<svg height="16" viewBox="0 0 16 16" version="1.1" width="16"><path fill="#28D751" d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>';

blocks.forEach((block) => {
    if (!navigator.clipboard) {
        return;
    }

    let button = document.createElement("button");
    button.className = "button-copy-code";
    button.ariaLabel = button.title = "Copiar";
    button.innerHTML = copyCodeIconSvg;
    block.appendChild(button);

    button.addEventListener("click", async () => {
        await copyCode(button, block);
    });
});

async function copyCode(button, block) {
    let copiedCode = block.cloneNode(true);
    copiedCode.removeChild(copiedCode.querySelector("button.button-copy-code"));

    const html = copiedCode.outerHTML.replace(/<[^>]*>?/gm, "");

    block.querySelector("button.button-copy-code").innerHTML = codeCopiedIconSvg;
    button.ariaLabel = button.title = "Copiado!";
    setTimeout(function () {
        block.querySelector("button.button-copy-code").innerHTML = copyCodeIconSvg;
        button.ariaLabel = button.title = "Copiar";
    }, 2000);

    const parsedHTML = htmlDecode(html);

    await navigator.clipboard.writeText(parsedHTML);
}

function htmlDecode(input) {
    const doc = new DOMParser().parseFromString(input, "text/html");
    return doc.documentElement.textContent;
}

CSS para os botões de copiar código

O CSS abaixo controla a posição e visibilidade dos botões:

pre[class*="shiki"] {
  position: relative;
  margin: 5px 0;
  padding: 1.75rem 0 1.75rem 1rem;
}

pre > .button-copy-code {
  position: absolute;
  top: 32px;
  right: 16px;
}

@media only screen and (max-device-width: 480px) {
  pre > .button-copy-code {
    display: none;
  }
}

Referências

Arquitetura assíncrona sem filas

2024-06-24T00:00:00Z

Arquitetura assíncrona

Uma estratégia comum em sistemas complexos é o assincronismo, que é deixar tarefas mais pesadas rodando em segundo plano e apenas quando elas forem acabadas receber um retorno delas. A idéia é entregar uma resposta mais imediata ao usuário, permitindo que ele possa fazer outras atividades enquanto isso. Essa abordagem existe tanto nas próprias linguagens de programação, por exemplo, através das palavras-chaves async / await, como também em arquitetura de sistemas, com um processamento orientado a mensagens ou eventos.

Existem filas dedicadas que são muito populares atualmente, como Apache Kafka e RabbitMQ, que são usadas para processamento assíncrono. Elas podem lidar com altos volumes de mensagens recebidas e processadas em paralelo, tratando também de concorrência de leitura e confirmação pós-processamento.

Apesar da popularidade dessas filas, outras alternativas mais leves e práticas podem ser utilizadas em substituição, resolvendo os mesmos problemas de maneira mais simples e até mais barata. Vamos conhecê-las.

Mensagens em bancos de dados

Aqui, um banco de dados guarda as mensagens. Há uma aplicação publicadora, que insere as mensagens no banco, e outra consumidora, que as lê.

Neste caso, as mensagens ficam persistidas e não correm risco de perdas por reinicializações. Tanto bancos SQL como NoSQL podem ser usados.

Como exemplo, podemos ter uma tabela em um banco de dados SQL que armazena as mensagens:

| Id |      Status      | Conteudo |
|----|------------------|----------|
|  1 | Processada       |   msg1   |
|  2 | Processada       |   msg2   |
|  3 | FalhaAoProcessar |   msg3   |
|  4 | EmProcessamento  |   msg4   |
|  5 | Aguardando       |   msg5   |
|  6 | Aguardando       |   msg6   |

A coluna Status serve como controle de quais mensagens já foram e quais ainda precisam ser processadas. Pelo menos quatro status devem existir:

Aguardando processamento
Em processamento
Falha ao processar
Processada

O status FalhaAoProcessar é muito importante, pois ele permite que os desenvolvedores analisem as mensagens com esse status a fim de identificar possíveis bugs de processamento e mensagens que vêm inválidas ou mal-formatadas.

Aqui, se houver mais de um consumidor simultâneo, devemos nos precaver contra concorrências de leitura, para evitar que uma mensagem seja processada mais de uma vez. A solução para isso é uma tranca.

Tranca no banco de dados

Uma tranca (mutex) restringe um acesso enquanto uma rotina detiver a posse dessa tranca.

Quando um consumidor for pegar a próxima mensagem para processar, ele deve trancar para leitura, para impedir que outros consumidores peguem a mesma mensagem que ele ao mesmo tempo. Se não conseguiu abrir a tranca, é porque outro consumidor chegou antes, assim, deve esperar a tranca ser liberada.

Durante o trancamento, a mensagem é obtida e marcada como EmProcessamento, e após isso, é liberada a leitura por outros consumidores.

Essa técnica existe em vários bancos de dados:

SQL Server: sp_getapplock com sp_releaseapplock
PostgreSQL: pg_advisory_xact_lock() com SET LOCAL lock_timeout = '4s'
MongoDB: db.coll.findAndModify()

O código abaixo é uma stored procedure em SQL Server que pega a próxima mensagem a ser lida usando uma tranca de aplicação (app lock).

CREATE OR ALTER PROCEDURE PegarMensagemParaProcessar
    @status VARCHAR(30)
AS
BEGIN TRANSACTION
    DECLARE @res INT
    -- trancando para leitura
    EXEC @res = sp_getapplock                 
         @Resource = 'TRANCA_PEGAR_MENSAGEM',
         @LockMode = 'Exclusive',
         @LockOwner = 'Transaction',
         @LockTimeout = 60000,
         @DbPrincipal = 'public';
    -- verifica se obteve a tranca
    IF @res NOT IN (0, 1)
    BEGIN
        RAISERROR ('Não foi possível trancar para leitura.', 16, 1)
    END 
    ELSE
    BEGIN    
      -- obtendo uma mensagem com o status que queremos
      DECLARE @msgId INT = (SELECT TOP 1 [Id] FROM [dbo].[Mensagens] WHERE [Status] = @status);
      -- marcando a mensagem com status 'EmProcessamento'
      UPDATE [dbo].[Mensagens] SET [Status] = 'EmProcessamento' WHERE [Id] = @msgId;
      -- retornando a mensagem para leitura
      SELECT * FROM [dbo].[Mensagens] WHERE [Id] = @msgId;
      -- liberando a tranca após leitura  
      EXEC @res = sp_releaseapplock 
           @Resource = 'TRANCA_PEGAR_MENSAGEM',
           @DbPrincipal = 'public',
           @LockOwner = 'Transaction';
    END    
COMMIT
GO

O consumidor deve executar o comando SQL:

EXECUTE PegarMensagemParaProcessar @status = 'Aguardando'

Invocação

Não há como o banco de dados proativamente invocar um consumidor, alertando este que há uma nova mensagem a ser processada. Assim, outras formas de acionamento devem ser usadas, como o consumidor periodicamente verificar se há novas mensagens; ou então cron jobs, que agendam a execução do consumidor em certos horários do dia.

Mensagens em caches distribuídos

Caches distribuídos, como o Redis, podem armazenar mensagens, que podem ficar dentro de pares chave-valor, filas e outras estruturas de dados.

Esta implementação pode ser considerada uma variação da apresentada acima.

Uma vantagem é que a implementação de filas vem de fábrica, poupando esforço de desenvolvimento.

Porém, como desvantagem, as mensagens podem ser perdidas em caso de reinicialização do cache, pois não há persistência (por ser um armazenamento volátil).

Exemplo de fila usando comandos do Redis:

# insere ao fim da fila
LPUSH minha_fila "Tarefa1"

# insere ao fim da fila
LPUSH minha_fila "Tarefa2"

# tira primeiro da fila: "Tarefa1"
RPOP minha_fila

# tira primeiro da fila: "Tarefa2"
RPOP minha_fila

Trancas distribuídas

Caches distribuídos podem fornecer trancas para evitar concorrência de leitura. A documentação do Redis detalha como implementar uma tranca distribuída de forma segura e considerando múltiplos consumidores.

Threads paralelas

Esta opção é muito prática quando se quer condensar o processamento em uma mesma aplicação — ela mesma produz e consome a mensagem internamente, em threads separadas.

A comunicação entre as threads de produção e consumo se dá através de filas concorrentes (thread-safe) no código, como os channels, em .NET, ou ConcurrentLinkedQueue, em Java. A thread de consumo deve rodar indefinidamente em plano de fundo, processando mensagens conforme elas chegam na fila.

Alguns cenários reais em que essa opção pode ser boa:

Cadastro de usuários: uma API recebe uma chamada para cadastrar um usuário, sendo que diversas etapas são executadas, como verificação de identidade, prevenção anti-fraudes e envio de email de confirmação para o usuário. Essas etapas podem ser leves o suficiente para não necessitarem rodar em uma aplicação apartada.
Logs e métricas: na maioria dos programas, o envio de logs e métricas se dá em threads em background.

Devemos levar em conta que esse processamento implica maior consumo de CPU e memória RAM na aplicação e pode competir com outras tarefas dela por esses recursos. Soluções para isso são escalabilidade vertical (aumentar CPU e RAM disponíveis) ou horizontal (distribuir a carga entre outras instâncias).

Exemplo prático

O código abaixo é de uma Minimal API do ASP.NET que usa channels para processar mensagens, que são recebidas em um endpoint HTTP e repassadas para um MyMessageProcessor.

Para rodar o programa abaixo:

Ter o .NET SDK instalado na máquina
Criar um projeto Minimal API:

# linha de comando
mkdir MinhaAPIChannels
cd ./MinhaAPIChannels/
dotnet new web

Copiar e colar o código abaixo no arquivo Program.cs
Rodar o projeto, dotnet run

using System.Threading.Channels;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

// criando o canal e o processador de mensagens
var channel = Channel.CreateUnbounded<MyMessage>();
builder.Services.AddSingleton<ChannelWriter<MyMessage>>(channel.Writer);
builder.Services.AddSingleton<ChannelReader<MyMessage>>(channel.Reader);
builder.Services.AddSingleton<MyMessageProcessor>();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");
// endpoint de recebimento de mensagens:
// GET /message?content=minha_mensagem_aqui
app.MapGet("/message",
    async
    (
        [FromQuery(Name = "content")] string? content,
        [FromServices] ILogger<MyMessage> logger,
        [FromServices] ChannelWriter<MyMessage> channelWriter
    ) => 
    {
        logger.LogInformation("Mensagem recebida: {content}", content);
        await channelWriter.WriteAsync(new(content));
        return Results.Ok();
    });

// necessário para iniciar o processamento
var msgProcessor = app.Services.GetService<MyMessageProcessor>();
msgProcessor!.IniciarProcessamento();

app.Run();

// classe da mensagem
public sealed record MyMessage(string? Content);

// classe do processador
public sealed class MyMessageProcessor
{
    private readonly ILogger<MyMessageProcessor> logger;
    private readonly ChannelReader<MyMessage> channelReader;

    public MyMessageProcessor(ILogger<MyMessageProcessor> logger,
                              ChannelReader<MyMessage> channelReader)
    {
        this.logger = logger;
        this.channelReader = channelReader;
    }

    public void IniciarProcessamento()
    {
        // inicia thread em background 
        // para processar mensagens
        Task.Factory.StartNew(async () =>
        {
            await foreach (var msg in channelReader.ReadAllAsync())
            {
                await ProcessarMensagemAsync(msg);
            }
        }, TaskCreationOptions.LongRunning);
    }

    private async Task ProcessarMensagemAsync(MyMessage msg)
    {
        logger.LogInformation("Mensagem em processamento: {content}", msg.Content);
        // operações aqui
        await Task.Delay(3000);
        logger.LogInformation("Mensagem processada: {content}", msg.Content);
    }
}

Para testar, basta ir no navegador Web e acessar a URL http://localhost:{porta}/message?content=minha_mensagem_aqui

Critérios de análise

Para decidir se uma arquitetura assíncrona é recomendada para seu caso, considere:

O usuário precisa receber uma resposta imediata?
Uma mensagem individual demora muito tempo para processar?
Uma mensagem individual gasta muita CPU e memória para processar?
As mensagens podem ser processadas em lotes (várias juntas de uma vez)?
O volume de mensagens é alto?

Várias respostas positivas acima indicam que ela é adequada.

Para escolher qual implementação usar, pergunte-se:

O processamento precisa ser iniciado de imediato?
A ordem de processamento importa?
Existe prioridade de mensagens?
Pode haver mais de um consumidor paralelo?
A eventual perda de uma mensagem seria tolerável?
Se uma mensagem for perdida, como recuperá-la?
Se uma mensagem for inválida ou improcessável, como tratá-la?
Se uma mensagem foi processada parcialmente, a retentativa causaria problemas?

As perguntas acima podem te ajudar a decidir qual estratégia de assincronia é a melhor para seu cenário.

Fontes e links interessantes

Introdução a programação funcional

2024-06-05T00:00:00Z

Paradigmas

Um paradigma é uma maneira de se pensar, de se observar e de se descrever algo ou um raciocínio; é um modelo mental, no qual nos baseamos para entender as coisas ao nosso redor. Cada pessoa tem um jeito próprio de enxergar o mundo e isso se reflete nas coisas que ela faz e produz.

Em programação, um código pode ser escrito de múltiplas formas e com resultados equivalentes — ou seja, o conceito de paradigmas se aplica.

Existem alguns paradigmas de programação que são os mais difundidos, entre eles:

Programação imperativa: Aqui, o programa é organizado em ordens: "faça isto", "faça aquilo", "se isso, então faça mais isso".
Programação orientada a objetos (POO): O foco é em quem (ou o quê) realiza uma ação. Cada objeto é um ator responsável por uma ação, e pode chamar outros objetos para realizarem outras ações.
Programação funcional (PF): Neste paradigma, o modelo é em torno de como se juntam as ações. Elas se encaixam como em uma linha de montagem, em que o fim de uma etapa desemboca no início da etapa seguinte, e no fim há um produto pronto.

Um pouco sobre PF

A programação funcional tem origem na matemática de funções.

Funções matemáticas podem ser compostas, tal que a saída de uma função é entrada de outra. Por exemplo:

f(x) = 3x + 1

g(x) = 2x

// composições

f ○ g (x) = f(g(x)) = 3(2x) + 1 = 6x + 1

g ○ f (x) = g(f(x)) = 2(3x + 1) = 6x + 2

O mesmo raciocínio se aplica na programação funcional: o retorno de um método é freqüentemente usado como valor de entrada para outro. O exemplo concreto abaixo mostra funções compostas na linguagem F#.

module Program =

    let f(x: int) = 3*x + 1

    let g(x: int) = 2*x

    let fg = g >> f // f(g(x)), saída de g é entrada de f

    let gf = f >> g // g(f(x)), saída de f é entrada de g

    let [<EntryPoint>] main _ =
        printfn "f(1) = %d" (f(1))
        printfn "g(1) = %d" (g(1))
        printfn "fg(1) = %d" (fg(1))
        printfn "gf(1) = %d" (gf(1))
        0

    // vai printar:
    // f(1) = 4
    // g(1) = 2
    // fg(1) = 7
    // gf(1) = 8

Quando usar programação funcional

A PF se destaca em tarefas de natureza matemática. Pense em cálculos de engenharia, de contabilidade, impostos, finanças, calendários e estatísticas. Ela também lida muito bem com categorizações e reconhecimento de padrões.

As áreas de inteligência artificial e aprendizado de máquina necessitam de matemática pesada e portanto podem se beneficiar da programação funcional.

Posso chamar um código funcional em um projeto POO ou imperativo?

Pode! Algumas linguagens orientadas a objeto permitem invocar código de linguagens funcionais, por exemplo, C# pode interagir com F#, e Java pode interagir com Scala.

Quando não usar programação funcional

Para tarefas como envio e recebimento de mensagens, ler e salvar informações em um banco de dados, ou publicação em filas, há poucas vantagens em se optar pela PF, pois a maioria das ações não se entrelaça. Nesses casos, uma linguagem POO ou imperativa normalmente é melhor.

Linguagem F#

Neste artigo, vamos usar a linguagem funcional F# para um estudo de caso. F# usa o runtime .NET.

Para preparar sua máquina para desenvolver em F#, você vai precisar instalar:

.NET SDK
Visual Studio ou
VS Code com a extensão F# language server updated (não usar a extensão do Ionide F#)

Para criar um projeto F# via linha de comando:

mkdir MeuProjetoFSharp
cd ./MeuProjetoFSharp/
dotnet new console --language F#

Antes de começar, algumas dicas de sintaxe:

Declaração de função:

// note que cada parâmetro tem um par de parênteses.
// a última linha é o retorno da função.
let soma(x: int)(y: int) =
  x + y

Função anônima / lambda:

fun x -> x * 2

Operador de descarte _

let minhaTupla = (1, 2)
// só a primeira parte interessa.
// a segunda é descartada `_`
let (x, _) = minhaTupla

Pipelining |>

let numeros = [ 1; 2; 3 ]
let dobrar(x: int) = x * 2
let incrementar(x: int) = x + 1

(*
|> significa que o resultado do anterior
é o último argumento da próxima função.

numeros |> Seq.map(incrementar)

é a mesma coisa que:

Seq.map(incrementar)(numeros)
*)

let numerosIncrementadosDobrados =
  numeros // 1, 2, 3
  |> Seq.map(incrementar) // 2, 3, 4
  |> Seq.map(dobrar) // 4, 6, 8

Estudo de caso: pôquer

No pôquer, um jogador tem uma mão com cinco cartas de baralho, cada carta definida por um naipe mais uma face. Existem quatro naipes (ouros ♦️, paus ♣️, copas ♥️ e espadas ♠️) e treze faces (2 a 10, valete J, dama Q, rei K, ás A). As cartas da mão podem formar combinações especiais e o jogador que tiver a combinação mais rara vence a rodada do jogo.

Combinação	Exemplo	Descrição	Chance
Royal Straight Flush	A️♦️, K♦️️️, Q♦️️️, J♦️️️, 10♦️️	Seqüência consecutiva de mesmo naipe, de 10 a ás.	0,000154%
Straight Flush	5♣️, 6♣️,️ 7♣️,️ 8♣️, 9♣️	Seqüência consecutiva de mesmo naipe (que não seja a real, acima).	0,00139%
Quadra	J♣️, J♠️,️ J♦️️️,️ J♥️️️, 2♣️️	Quatro cartas de mesma face.	0,02401%
Full House	4♣️, 4♦️️️,️ 10♦️️, 10♣️️, 10♠️	Uma trinca e um par.	0,1441%
Flush	4♥️️️, 7♥️️️,️ 8♥️️️, J♥️️️, A♥️️️	Cartas de mesmo naipe, mas sem formar seqüência consecutiva.	0,1965%
Straight	A♥️️️, 2♣️,️ 3♥️️️, 4♦️️️, 5♠️	Seqüência consecutiva de faces, mas com naipes distintos.	0,3925%
Trinca	2♦️️, K♣️,️ 7♦️️️, 7♣️, 7♠️	Três cartas de faces iguais.	2,1128%
Dois pares	8♥️️️,️ 8♦️️️, 9♥️️️, 9♠️, 7♥️️	Dois pares de cartas.	4,7539%
Par	10♦️️,️ K♠️, K♥️️️, 2♠️, 5♠️	Duas cartas de mesma face.	42,2569%
Carta mais alta	6♦️️, 3♦️️, 10♥️️,️ 7♦️️, 2♦️️	Quando a mão não corresponde a uma das combinações acima.	50,1177%

Domínio de um jogo de pôquer

namespace Poker.Domain

module PokerGame =

    // esta é uma união discriminada
    type Naipe = Espadas | Paus | Copas | Ouros

    // este é um enum
    type Face =
    | Dois = 2 | Três = 3 | Quatro = 4 | Cinco = 5 | Seis = 6 | Sete = 7 | Oito = 8
    | Nove = 9 | Dez = 10 | Valete = 11 | Dama = 12 | Rei = 13 | Ás = 14

    // isto é uma tupla
    type Carta = Naipe * Face

    type Mao = Carta list

    type CombinacaoMao =
    | RoyalStraightFlush = 10
    | StraightFlush = 9
    | Quadra = 8
    | FullHouse = 7
    | Flush = 6
    | Straight = 5
    | Trinca = 4
    | DoisPares = 3
    | Par = 2
    | CartaMaisAlta = 1

    let temStraight(mao: Mao) =
        mao
        |> Seq.sortBy(fun (_,face) -> face)
        |> Seq.pairwise
        |> Seq.forall(fun ((_,face1), (_,face2)) ->
            (int face2) - (int face1) = 1 || (face2 = Face.Ás && face1 = Face.Cinco))

    let temFlush(mao: Mao) =
        let (umNaipe, umaFace) = Seq.head mao
        mao
        |> Seq.map (fun (naipe,_) -> naipe)
        |> Seq.forall ((=)umNaipe)

    let temReiAs(mao: Mao) =
        let temUmRei = Seq.exists(fun (_,face) -> face = Face.Rei)(mao)
        let temUmAs = Seq.exists(fun (_,face) -> face = Face.Ás)(mao)
        temUmRei && temUmAs

    let obterEmOrdemCrescenteQuantidadesPorFace(mao: Mao) =
        mao
        |> Seq.countBy(fun (_, face) -> face)
        |> Seq.sortBy(fun (_, qtdPorFace) -> qtdPorFace)
        |> Seq.map(fun (_, qtdPorFace) -> qtdPorFace)
        |> Seq.toList

    let obterCombinacaoMao(mao: Mao) =
        match obterEmOrdemCrescenteQuantidadesPorFace(mao) with
        | [ 1; 4 ] -> CombinacaoMao.Quadra
        | [ 2; 3 ] -> CombinacaoMao.FullHouse
        | [ 1; 1; 3 ] -> CombinacaoMao.Trinca
        | [ 1; 2; 2 ] -> CombinacaoMao.DoisPares
        | [ 1; 1; 1; 2 ] -> CombinacaoMao.Par
        | _ -> match (temStraight(hand), temFlush(hand), temReiAs(hand)) with
               | (true, true, true) -> CombinacaoMao.RoyalStraightFlush
               | (true, true, false) -> CombinacaoMao.StraightFlush
               | (true, false, _) -> CombinacaoMao.Straight
               | (false, true, _) -> CombinacaoMao.Flush
               | _ -> CombinacaoMao.CartaMaisAlta

Em apenas um arquivo, conseguimos descrever a lógica do problema a ser resolvido. Ainda que a sintaxe da linguagem não seja familiar para quem vê pela primeira vez, há um padrão lógico de transformações e comparações nos métodos.

O último método, obterCombinacaoMao, compara as quantidades de cartas por face para saber se há uma combinação por quantidade (quadras, trincas, full houses, dois pares e pares). Se não houver, então analisa se a combinação é seqüencial e/ou de naipe (straight, flush, straight flush e royal straight flush). Por fim, se não houver correspondência, então é carta mais alta.

Confesso que quando mexi com linguagem funcional pela primeira vez eu achei difícil, um pouco por causa da sintaxe que é bem diferente, e também porque vários exemplos de código na internet usam tipagem implícita, que é menos óbvia de se entender:

// tipagem implícita (inferência)
let soma x y =
  x + y

// declaração mais explícita possível
let soma(x: int)(y: int): int =
  x + y

Contudo, se você tem alguma situação em que uma abordagem funcional é melhor, digo que vale a pena persistir e aprender, começando com exemplos mais simples e pequenos, e progredir conforme se sentir mais seguro.

O código acima está disponível no GitHub, com testes unitários e mostrando como integrar um projeto F# com um projeto C#.

Arquivos fs para compilação

Se você estiver usando VS Code, sempre que adicionar um arquivo .fs ao seu projeto, lembre de incluí-lo no .fsproj:

<ItemGroup>
  <Compile Include="Library.fs" />
  <Compile Include="Module2.fs" />
</ItemGroup>

Fontes e links interessantes

Pipelines para .NET

2024-04-29T00:00:00Z

Pipelines

As esteiras automatizadas, também conhecidas como pipelines, são seqüências de comandos executados para garantir a integridade do seu código e para gerar um artefato final, como um programa executável ou uma biblioteca.

Ter uma pipeline significa ter um processo consistente que minimiza o risco de erros humanos no produto final e economiza tempo do programador, pois ele pode se ocupar de outras tarefas enquanto o código é compilado, verificado e empacotado.

Etapas

flowchart TD
    checkout -->
    clean --> 
    restore -->
    audit -->
    sbom -->
    build -->
    unittests[unit tests]
    unittests --se for programa--> publish --com docker--> dockerk8s[docker / kubernetes]
    publish --sem docker--> zipinstaller[zip / instalador]
    unittests --se for pacote nuget--> pack --> nugetpush[nuget push]

checkout

Obtém o código da branch em questão, no Git. Se for um processo de integração (CI), pega o código da branch que pretende ser mergeada; se for um deploy (CD), pega o código da branch de publicação, como develop, master ou release_candidate.

Linha de comando: git clone

clean

Limpa as pastas bin e obj, para garantir que tudo vai começar do zero, sem interferências de compilações anteriores.

Linha de comando: dotnet clean

restore

Garante que as referências entre os projetos na solução estão corretas e faz o download dos pacotes NuGet necessários.

Linha de comando: dotnet restore

audit

Verifica se há algum pacote NuGet do projeto com problemas de segurança, conferindo nas listas de vulnerabilidades CVE (Common Vulnerabilities and Exposures) e GHSA (GitHub Advisory Database).

Linha de comando: dotnet list package --vulnerable --include-transitive

sbom

O SBOM, em inglês, software bill of materials, é um documento que informa quais componentes foram utilizados para a produção de um programa ou biblioteca.

Esse documento é de suma importância para softwares críticos, pois através dele, as organizações podem facilmente saber quais de suas aplicações estão em perigo quando uma vulnerabilidade em uma biblioteca é reportada. Após o ciberataque ao governo dos EUA em 2020, os SBOMs tornaram-se uma prática endossada pela Casa Branca.

Recomendo o formato CycloneDX, por ser mais sucinto e de leitura mais fácil.

Linha de comando:

Em formato CycloneDX: dotnet CycloneDX
Em formato SPDX: sbom-tool generate

build

Compila o código da solução.

Linha de comando: dotnet build

unit tests

Roda os testes unitários da solução para assegurar que estão passando.

Nessa etapa, podemos produzir um relatório que exibe o nível de cobertura dos testes unitários em relação ao código, mostrando quais classes, métodos e linhas foram abrangidos pelos testes. O ReportGenerator é a principal ferramenta para esses relatórios em projetos .NET.

Linha de comando:

Testes unitários: dotnet test
Relatório de cobertura: reportgenerator

publish

Gera o programa final, voltado para execução. Essa etapa difere do build porque nesta, pode-se especificar opções de compilação, como o runtime de destino, se é self-contained, se é single-file, entre outras.

Linha de comando: dotnet publish

pack

Produz um pacote NuGet, no caso de um código que é feito para ser uma biblioteca.

Linha de comando: dotnet pack

nuget push

Sobe o pacote para um servidor NuGet, privado ou público, para que possa ser utilizado por outras pessoas.

Linha de comando: dotnet nuget push

Motores de pipeline

Existem vários motores de pipeline disponíveis, como o GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, CircleCI e diversos outros.

Além desses, você pode ter sua pipeline como um script para rodar localmente na sua máquina. Essa é uma boa prática por ser uma salvaguarda caso sua pipeline remota esteja fora do ar e porque permite testar modificações antes de commitá-las.

Recomendo pessoalmente usar scripts PowerShell para pipelines locais, pois é uma linguagem multiplataforma e amigável, com fácil interação com XML e JSON. Contudo, você pode usar outras linguagens de script, como Batch, Shell, Python e outras que você preferir.

Exemplo em GitHub Actions para programa .NET

name: Publicar console / API / programa desktop

on:
  workflow_dispatch: # acionamento manual
    inputs:
      version:
        required: true
        type: string
      rid:
        required: true
        default: linux-x64 # onde o programa vai rodar
        type: string
        # https://learn.microsoft.com/en-us/dotnet/core/rid-catalog

jobs:
  gerar_programa:

    runs-on: ubuntu-latest

    env:
      OUTPUT_FOLDER: ${{ format('./out/{0}/', inputs.rid) }}
      VERSION_NAME: ${{ inputs.version }}
      RID: ${{ inputs.rid }}

    steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 1

    - name: Instalar .NET SDK
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 8.x # versão do .NET aqui

    - name: Instalar CycloneDX .NET
      run: dotnet tool install --global CycloneDX

    - name: Limpar solução
      run: dotnet clean --nologo --verbosity quiet
    
    - name: Restaurar solução
      run: dotnet restore --nologo --verbosity quiet

    - name: Auditar solução
      shell: pwsh
      run: |
        $projectPath = "./src/MeuProjeto.Console/MeuProjeto.Console.csproj"
        $jsonObj = (dotnet list $projectPath package --vulnerable --include-transitive --format json) | ConvertFrom-Json;
        $hasAnyVulnerability = ($jsonObj.projects[0].frameworks -ne $null);
        if ($hasAnyVulnerability) {
          dotnet list package --vulnerable --include-transitive;
          exit 1;
        }

    - name: Compilar solução
      run: dotnet build --no-restore --configuration Release --nologo --verbosity quiet

    - name: Rodar testes unitários
      run: dotnet test --no-build --configuration Release --nologo --verbosity quiet --collect:"XPlat Code Coverage" --results-directory ./TestResults/

    - name: Relatório de cobertura de testes unitários
      uses: danielpalme/ReportGenerator-GitHub-Action@5.2.4
      with:
        reports: TestResults/**/coverage.cobertura.xml
        targetdir: TestResults
        reporttypes: JsonSummary;Html

    - name: Gerar SBOM
      shell: pwsh
      run: dotnet CycloneDX ./src/MeuProjeto.Console/MeuProjeto.Console.csproj -o $env:OUTPUT_FOLDER -f sbom.json -sv $env:VERSION_NAME --json

    - name: Publicar programa
      shell: pwsh
      run: |
        dotnet publish ./src/MeuProjeto.Console/MeuProjeto.Console.csproj `
        --verbosity quiet `
        --nologo `
        --configuration Release `
        -p:PublishSingleFile=true `
        -p:Version=${env:VERSION_NAME} `
        --self-contained true `
        --runtime ${env:RID} `
        --output ${env:OUTPUT_FOLDER};

    - name: Setar atributos de execução (UNIX apenas)
      if: ${{ startsWith(inputs.rid, 'linux') || startsWith(inputs.rid, 'osx') }}
      shell: pwsh
      run: chmod +x "${env:OUTPUT_FOLDER}/MeuProjeto.Console"

    - name: Empacotar programa
      shell: pwsh
      run: |
        $zipName = "MeuProjeto.Console_${env:VERSION_NAME}_${env:RID}.zip";
        # se for Linux ou MacOSX, devemos usar o zip ao invés do Compress-Archive,
        # para preservar os atributos de arquivos do Unix.
        if ($IsWindows) {
          Compress-Archive -CompressionLevel Optimal -Path $env:OUTPUT_FOLDER -DestinationPath "./out/${zipName}"
        } else {
          cd $env:OUTPUT_FOLDER
          zip -9 -r ../${zipName} *
          cd ../..
        }
        Remove-Item $env:OUTPUT_FOLDER -Force -Recurse -ErrorAction Ignore
        echo "OUTPUT_FILE_NAME=${zipName}" | Out-File -FilePath $Env:GITHUB_ENV -Encoding utf8 -Append

    - name: Subir programa para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        compression-level: 0 # não precisa comprimir pq passo anterior já comprime
        name: ${{ env.OUTPUT_FILE_NAME }}
        path: ${{ format('./out/{0}', env.OUTPUT_FILE_NAME) }}
    
    - name: Subir SBOM para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        name: sbom.json
        path: ./out/sbom.json
    
    - name: Subir relatório de cobertura para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        name: relatorio_de_cobertura
        path: TestResults
    
    # outras etapas subseqüentes podem ser adicionadas aqui,
    # como docker e kubernetes,
    # ou geração de instalador, no caso de programas desktop.

Exemplo em GitHub Actions para pacote NuGet

name: Publicar pacote NuGet

on:
  workflow_dispatch: # acionamento manual

jobs:
  gerar_pacote_nuget:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 1

    - name: Instalar .NET SDK
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 8.x # versão do .NET aqui

    - name: Instalar CycloneDX .NET
      run: dotnet tool install --global CycloneDX

    - name: Limpar solução
      run: dotnet clean --nologo --verbosity quiet
    
    - name: Restaurar solução
      run: dotnet restore --nologo --verbosity quiet

    - name: Auditar solução
      shell: pwsh
      run: |
        $projectPath = "./src/MeuProjeto.Console/MeuProjeto.Console.csproj"
        $jsonObj = (dotnet list $projectPath package --vulnerable --include-transitive --format json) | ConvertFrom-Json;
        $hasAnyVulnerability = ($jsonObj.projects[0].frameworks -ne $null);
        if ($hasAnyVulnerability) {
          dotnet list package --vulnerable --include-transitive;
          exit 1;
        }

    - name: Compilar solução
      run: dotnet build --no-restore --configuration Release --nologo --verbosity quiet

    - name: Rodar testes unitários
      run: dotnet test --no-build --configuration Release --nologo --verbosity quiet --collect:"XPlat Code Coverage" --results-directory ./TestResults/

    - name: Relatório de cobertura de testes unitários
      uses: danielpalme/ReportGenerator-GitHub-Action@5.2.4
      with:
        reports: TestResults/**/coverage.cobertura.xml
        targetdir: TestResults
        reporttypes: JsonSummary;Html
    
    - name: Ler versão do pacote
      shell: pwsh
      run: |
        # o PackageVersion deve estar declarado no .csproj
        ([XML]$nugetCsprojXml = Get-Content ./src/MeuProjeto.Biblioteca/MeuProjeto.Biblioteca.csproj)
        $versionName = $nugetCsprojXml.Project.PropertyGroup.PackageVersion
        # adiciona às variáveis de ambiente do workflow
        echo "VERSION_NAME=${versionName}" | Out-File -FilePath $Env:GITHUB_ENV -Encoding utf8 -Append

    - name: Gerar SBOM
      shell: pwsh
      run: dotnet CycloneDX ./src/MeuProjeto.Biblioteca/MeuProjeto.Biblioteca.csproj -o ./out/ -f sbom_meuprojeto_biblioteca.json -sv $env:VERSION_NAME --json

    - name: Gerar pacote
      run: dotnet pack ./src/MeuProjeto.Biblioteca/MeuProjeto.Biblioteca.csproj --nologo --verbosity quiet --configuration Release
    
    - name: Subir pacote para servidor NuGet
      shell: pwsh
      run: |
        $filePath = "./src/MeuProjeto.Biblioteca/bin/Release/MeuProjeto.Biblioteca.${env:VERSION_NAME}.nupkg"
        dotnet nuget push $filePath --api-key $env:NUGET_API_KEY --source https://api.nuget.org/v3/index.json
        # se for um servidor NuGet privado, usar outro source.
        # portal web para testes do NuGet: https://int.nugettest.org
        # source para testes: https://apiint.nugettest.org/v3/index.json
      env:
        NUGET_API_KEY: ${{ secrets.MINHA_NUGET_API_KEY }}

    - name: Subir pacote para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        compression-level: 0 # não precisa comprimir pq .nupkg já é um zip
        name: ${{ format('MeuProjeto.Biblioteca.{0}.nupkg', env.VERSION_NAME) }}
        path: ${{ format('./src/MeuProjeto.Biblioteca/bin/Release/MeuProjeto.Biblioteca.{0}.nupkg', env.VERSION_NAME) }}

    - name: Subir SBOM para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        name: sbom_meuprojeto_biblioteca.json
        path: ./out/sbom_meuprojeto_biblioteca.json
    
    - name: Subir relatório de cobertura para resultados do workflow
      uses: actions/upload-artifact@v4
      with:
        name: relatorio_de_cobertura
        path: TestResults

Fonte da imagem

https://dyno.co.nz/products/telescopic-and-expandable-conveyors/telescopic-conveyor/

HTTP/2 e HTTP/3 explicados

2024-03-11T00:00:00Z

No início da década de 1990, Tim Berners-Lee e sua equipe no CERN trabalharam juntos para formar a base da World Wide Web, definindo quatro peças-chaves para a rede mundial de computadores:

Um formato de documento para hipertexto (o HTML)
Um protocolo de transmissão de dados (o HTTP)
Um navegador de internet para exibir hipertexto (o primeiro navegador, WorldWideWeb)
Um servidor para transmitir esses dados (uma versão inicial do httpd)

O HTTP, em questão, aproveitou os protocolos TCP/IP já existentes como meio de transporte de dados. Os bytes de uma mensagem HTTP ficam na camada de aplicação, em azul claro na imagem abaixo.

HTTP/0.9

Foi a primeira versão de rascunho do HTTP. O único método existente era o GET; não havia cabeçalhos nem status codes; e o único formato possível de resposta era o HTML. Assim como no HTTP/1.0 e no HTTP/1.1, as mensagens HTTP seguiam um formato de texto em ASCII.

Exemplo de requisição HTTP/0.9:

GET /mypage.html

Exemplo de resposta:

<html>
  A very simple HTML page
</html>

HTTP/1.0

Esta versão deu ao HTTP a sua estrutura atual, parecida com a de um memorando, com cabeçalhos e conteúdo, também introduzindo novos métodos (HEAD e POST), MIME types, status codes e versionamento do protocolo.

Exemplo de requisição HTTP/1.0:

GET /mypage.html HTTP/1.0
User-Agent: NCSA_Mosaic/2.0 (Windows 3.1)

Exemplo de resposta:

200 OK
Date: Tue, 15 Nov 1994 08:12:31 GMT
Server: CERN/3.0 libwww/2.17
Content-Type: text/html

<HTML>
A page with an image
  <IMG SRC="/myimage.gif">
</HTML>

HTTP/1.1

Esta versão surgiu no início de 1997, poucos meses depois da predecessora. As principais mudanças foram:

Reaproveitamento de conexões TCP (keep-alive), poupando recursos da máquina e de rede. Na versão anterior, uma conexão nova era criada para cada requisição e encerrada logo após a resposta.
Cabeçalho Host, permitindo que mais de um servidor esteja alocado sob um mesmo IP.
Convenções de cabeçalhos de encoding, cache, idioma e MIME type.

Exemplo de requisição HTTP/1.1:

GET /api/fruit/orange HTTP/1.1
Host: www.fruityvice.com
Accept-Encoding: gzip, deflate, br

Exemplo de resposta:

HTTP/1.1 200 OK
Server: nginx/1.16.1
Date: Sun, 10 Mar 2024 20:44:25 GMT
Transfer-Encoding: chunked
Connection: keep-alive
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Pragma: no-cache
X-Frame-Options: DENY
Content-Type: application/json
Expires: 0

{"name":"Orange","id":2,"family":"Rutaceae","order":"Sapindales","genus":"Citrus","nutritions":{"calories":43,"fat":0.2,"sugar":8.2,"carbohydrates":8.3,"protein":1.0}}

HTTP/2

Em 2015, após muitos anos de observação e estudos sobre a performance da internet em geral, foi proposto e criado o HTTP/2, uma nova versão, baseada no SPDY do Google.

Dentre as principais mudanças, estão a multiplexação de várias mensagens dentro de um único pacote TCP; formato binário das mensagens; e compressão dos cabeçalhos, com HPACK.

No HTTP/1.1, duas requisições HTTP não podem trafegar juntas em uma mesma conexão TCP — é necessário que a primeira delas termine para que a subseqüente se inicie. Isso se chama bloqueio de cabeça de fila (head-of-line blocking, em inglês). No diagrama abaixo, a requisição 2 não pode começar até que a resposta 1 tenha chegado, considerando que apenas uma conexão TCP é usada.

sequenceDiagram
    Cliente->>+Servidor: req 1
    Servidor-->>-Cliente: res 1
    Cliente->>+Servidor: req 2
    Servidor-->>-Cliente: res 2

Com o HTTP/2, esse problema é resolvido através de streams: cada stream corresponde a uma mensagem. Vários streams podem estar entremeados dentro de um mesmo pacote TCP. Se um stream não puder emitir dados por algum motivo, outros podem aproveitar e entrar em seu lugar no pacote TCP.

Os streams são divididos em frames, cada um contendo: o tipo do frame, o stream ao qual pertence, e o comprimento em bytes. No diagrama abaixo, um retângulo colorido é um pacote TCP e um ✉ é um frame HTTP/2. O primeiro e o terceiro pacotes TCP carregam frames de streams diferentes.

sequenceDiagram
    rect rgb(239, 190, 125)
        Cliente->>+Servidor: req1: #9993;1/1<br>+<br>req2: #9993;1/1
    end
    rect rgb(197, 234, 189)
        Servidor-->>Cliente: res1: #9993;1/2
    end
    rect rgb(197, 234, 189)
        Servidor-->>-Cliente: res1: #9993;2/2<br>+<br>res2: #9993;1/1
    end

A imagem abaixo mostra como os frames entram em pacotes TCP. O stream 1 representa uma resposta HTTP de um arquivo JavaScript e o stream 2 representa uma resposta HTTP de um arquivo CSS, transmitidos via HTTP/2.

HTTP/3

O HTTP/3 surgiu diante de um novo protocolo de transporte proposto pelo Google, o QUIC, em 2012. O QUIC é encapsulado dentro do UDP, e comparado ao TCP, propõe:

menos roundtrips (idas-e-voltas) de pacotes para estabelecimento de conexão e estabelecimento de criptografia TLS;
ter conexões mais resilientes quanto a perda de pacotes;
resolver o bloqueio de cabeça de fila que existe no protocolo TCP e no TLS.

O HTTP/2 consegue resolver o bloqueio de cabeça de fila relacionado ao HTTP, porém, esse tipo de bloqueio também existe no protocolo TCP e no TLS. O TCP entende que os dados que deve enviar fazem parte de uma seqüência de pacotes contígüos, e se um desses pacotes for perdido, ele deve ser reenviado para o destinatário, a fim de que se preserve a integridade da informação. No TCP, pacotes subseqüentes não podem ser enviados enquanto o pacote perdido não chegar com sucesso no destino.

O diagrama abaixo explica visualmente como isso ocorre no HTTP/2. O segundo pacote tinha frames apenas da resposta 1, porém a perda dele atrasa tanto a resposta 1 como a resposta 2 — ou seja, não há paralelismo nesse caso.

sequenceDiagram
    rect rgb(239, 190, 125)
        Cliente->>+Servidor: req1: #9993;1/1<br>+<br>req2: #9993;1/1
    end
    rect rgb(197, 234, 189)
        Servidor--xCliente: res1: #9993;1/2
    end
    Note over Cliente,Servidor: pacote TCP perdido<br>precisa ser reenviado.<br>atrasa tanto res1 como res2
    rect rgb(197, 234, 189)
        Servidor-->>Cliente: res1: #9993;1/2
    end
    rect rgb(197, 234, 189)
        Servidor-->>-Cliente: res1: #9993;2/2<br>+<br>res2: #9993;1/1
    end

Para resolver o bloqueio de cabeça de fila do TCP, o QUIC opta por utilizar o UDP como protocolo de transporte, pois este é um protocolo sem garantias de recebimento. A responsabilidade de garantia de integridade, que no TCP fica na camada de transporte, passa no QUIC para a camada de aplicação, de modo que os frames de uma mensagem podem chegar fora de ordem, sem bloquear streams não-relacionados.

sequenceDiagram
    rect rgb(255, 179, 217)
        Cliente->>Servidor: req1: #9993;1/1<br>+<br>req2: #9993;1/1
    end
    rect rgb(179, 205, 230)
        Servidor--xCliente: res1: #9993;1/2
    end
    Note over Cliente,Servidor: pacote QUIC perdido<br>não bloqueia outros pacotes
    rect rgb(179, 205, 230)
        Servidor-->>Cliente: res1: #9993;2/2<br>+<br>res2: #9993;1/1
    end
    Note over Cliente,Servidor: reenvio do pacote perdido.<br>res2 não foi afetado
    rect rgb(179, 205, 230)
        Servidor-->>Cliente: res1: #9993;1/2
    end

O bloqueio de cabeça de fila relacionado ao TLS (criptografia SSL) ocorre no TCP porque a criptografia é geralmente aplicada sobre a mensagem inteira, de modo que todos os seus pacotes precisam chegar ao destino para então ocorrer a decriptação. No caso do QUIC, a criptografia é individual para cada pacote QUIC, que é decriptado na chegada, sem haver a necessidade de receber todos os pacotes primeiro.

TLS com TCP:

Dados de entrada: A+B+C
Dados encriptados: crypt(A+B+C) = D+E+F
Pacotes: D, E, F
Recebimento: decrypt(D+E+F)
A+B+C

TLS com QUIC:

Dados de entrada: A+B+C
Dados encriptados: crypt(A) = X, crypt(B) = Y, crypt(C) = Z
Pacotes: X, Y, Z
Recebimento: decrypt(X) + decrypt(Y) + decrypt(Z)
A+B+C

Tabela de comparação

	HTTP/1.1	HTTP/2	HTTP/3
Protocolo de transporte	TCP, conexão persistente	TCP, conexão persistente	UDP, conexão persistente
Bloqueio de cabeça de fila *(HOL blocking)*	HTTP/1.x HOL TCP HOL TLS HOL	TCP HOL TLS HOL	-
Formato das mensagens	texto em ASCII	binário	binário
Compressão de cabeçalhos	-	HPACK	QPACK
Nº de idas-e-voltas para iniciar (handshakes)	3 1 do TCP +2 do TLS 1.2*	2 1 do TCP +1 do TLS 1.3*	0 0 do UDP +0 do TLS 1.3 com 0-RTT*
Identificação de conexão	IP e porta de origem	IP e porta de origem	connection ID**, resistente a mudanças de IP
Criptografia	não obrigatória; aplicada na mensagem inteira	não obrigatória; aplicada na mensagem inteira	TLS 1.3 embutido; aplicada por pacote QUIC

* O TLS 1.2 requer 2 roundtrips para handshake criptográfico e o TLS 1.3 requer apenas 1, com a opção de 0-RTT (zero roundtrip time resumption), em que não há necessidade de handshake prévio. Porém, o 0-RTT possibilita ataques de replay e por isso é inseguro. Ele é opcional e pode ser deixado desabilitado.

** O connection ID do QUIC pode ser usado para fingerprinting, colocando em risco a privacidade dos usuários, segundo pesquisa.

Qual é a melhor versão?

As duas melhores versões atualmente são o HTTP/2 e o HTTP/3.

O HTTP/3 foi desenhado para conexões instáveis, como redes de telefonia celular e de satélite. Para contornar instabilidades de rede, o QUIC tem grande independência dos fluxos de dados e resiliência caso pacotes sejam perdidos. Porém, o HTTP/3 tem desvantagens de performance, em razão de 1) o protocolo UDP não ter sido otimizado pelos sistemas operacionais e roteadores ao longo das últimas décadas, devido ao baixo uso dele em geral, tornando-o comparativamente mais lento do que o TCP; e 2) a criptografia pacote-por-pacote no QUIC requer um número maior de operações matemáticas, tornando-a menos eficiente do que a criptografia de mensagem inteira no TCP. Há ainda o problema de o protocolo UDP (usado pelo QUIC) ser restringido em algumas redes para proteger contra, por exemplo, ataque de inundação de UDP e ataque de amplificação de DNS.

Em conexões confiáveis e plenas, o HTTP/2 muitas vezes oferece performance melhor do que o HTTP/3.

Para evitar o bloqueio de cabeça de fila no HTTP/1.x, muitos navegadores e HTTP clients abrem várias conexões TCP, para que as requisições corram em paralelo. Em cenários com muitas requisições e respostas pesadas em paralelo, essa técnica pode fazer com que o HTTP/1.x ofereça maior taxa de transferência (throughput) comparado ao HTTP/2 ou HTTP/3, porém, é uma forma menos eficiente de se resolver o problema. Uma solução alternativa é ter múltiplas conexões HTTP/2-3 ao mesmo tempo (exemplo em C#).

De modo geral, recomenda-se realizar testes de compatibilidade e de performance para decidir qual é a versão mais indicada, além disso, um servidor pode aceitar conexões tanto de HTTP/2 como de HTTP/3, cabendo ao cliente decidir qual versão usar.

Ferramenta de testes

Recomendo o Pororoca (feito por mim 🙂).

Bibliografia

Formatos de imagem modernos: JXL e AVIF

2024-01-28T00:00:00Z

Computação, fotografia e imagens

A visualização de imagens é fundamental em vários setores, como artes plásticas, fotografias profissionais, cartografia, astrofotografia, medicina diagnóstica, preservações históricas e cinema. A qualidade das imagens é muito importante para se notar detalhes, como um toque artístico, uma imprecisão, ou um elemento imperceptível à primeira vista.

Em uma tela de computador, uma imagem é representada por milhares de pixels (picture element), cada pixel correspondendo a uma cor e sua intensidade. Considere uma imagem de tamanho 1.024px x 768px = 786.432 pixels; se cada pixel for RGBA e tiver 4 bytes, 1 para vermelho, 1 para verde, 1 para azul e 1 para transparência, essa imagem terá um tamanho de 3,1MB, o que é bastante alto. Contudo, escolhendo técnicas de compressão e um formato de arquivo adequados, podemos ter essa imagem com a mesma qualidade e ocupando muito menos espaço em memória.

Novos formatos

Por volta de 2019, surgiram no mercado dois novos formatos de arquivo, o JXL e o AVIF, prometendo menor consumo de memória em disco e maior preservação de detalhes.

Ambos compartilham como características:

Compressão com perdas (lossy compression), ou sem perdas (lossless compression), mais eficiente do que formatos predecessores, como o JPEG e PNG, e retendo alta definição.
Suporte a animações e transparências.
Open-source e licença livre de royalties.

JXL

O JXL, ou JPEG-XL, começou em 2017 com uma chamada de propostas para um formato de imagem de nova geração. A proposta final foi a junção de duas outras: a PIK, do Google, e a FLIF, da Cloudinary.

AVIF

O AVIF é um formato criado pela Alliance for Open Media, um consórcio de várias empresas de tecnologia, como a Netflix, Meta e Google, com o objetivo de formar padrões de mercado para mídia digital. A primeira especificação do AVIF é de 2018.

Quando devo usar o JXL?

O JXL é melhor para:

Imagens de alta e extrema alta resolução e nível de detalhes.
Situações em que a velocidade de processamento é importante, pois o encoding do JXL é de 5 a 10 vezes mais rápido do que o AVIF.
Altíssima precisão de côres.
Decoding progressivo: a imagem pode ser visualizada conforme é baixada.
Imagens de dimensões muito grandes, pois suporta tamanhos de mais de 1 bilhão x 1 bilhão de pixels. O AVIF suporta imagens em no máximo 8K (8193px x 4320px).

Quando devo usar o AVIF?

O AVIF é melhor para:

Imagens em páginas Web, pois a maioria dos navegadores suporta AVIF (94%), enquanto que poucos navegadores suportam JXL (15%). Dados obtidos pelo caniuse (08/05/2026).
Vídeos e animações, pois tem excelente taxa de compressão para eles, acima de 90% em alguns casos. É um ótimo substituto aos GIFs.

Testes de compressão e performance

Exemplos:

A imagem original abaixo é um JPG de dimensões 8192x5464, com tamanho de 11MB. Em formato JXL (q=90), o tamanho ficou em 7,3MB. Em AVIF (q=90), ficou em 8,3MB.

O GIF original abaixo tem tamanho de 3,1MB. Em formato JXL (q=90), o tamanho ficou em 2,5MB. Em AVIF (q=90), ficou em 79kB. Impressionante!

Este repositório no GitHub (link) executa testes para comparar as velocidades e taxas de compressão do JXL e do AVIF. A comparação não é qualitativa, nem científica. Como imagens de entrada, estão:

GIFs animados de alta, média e baixa complexidade.
Fotografias em JPEG de média, alta e altíssima resolução.
Infográficos em PNG e JPEG, para avaliar a compressão de imagens com textos.

Ferramentas

Existem sites na internet que podem fazer conversões para AVIF e JXL. Eu recomendo o ezgif.

A maioria dos navegadores suporta abrir arquivos .avif.

Para visualizar JXL, há o GIMP, o Irfanview e outros programas.

Conversão para `.jxl`

Para converter uma imagem para JXL, usando a ferramenta oficial:

cjxl img_entrada.jpg img_saida.jxl -q 90 --lossless_jpeg=0

Conversão para `.avif`

Há duas ferramentas principais: o cavif-rs e o ffmpeg. O cavif-rs atualmente não suporta GIFs, então para estes devemos usar o ffmpeg.

Para converter uma imagem estática para AVIF, usando o cavif-rs:

cavif img_entrada.jpg -o img_saida.avif -Q 90 -f

Para converter uma GIF para AVIF usando o ffmpeg, você precisará também da libavif.

# sudo apt install ffmpeg
# sudo apt install libavif-bin

# primeiro, converter de .gif para .y4m
ffmpeg -i entrada.gif -pix_fmt yuv420p -f yuv4mpegpipe temp.y4m

# depois, de .y4m para .avif
avifenc temp.y4m saida.avif

Exibição em HTML com fallback

Se você quer usar esses novos formatos, mas quer garantir compatibilidade com navegadores Web mais antigos, você pode usar a tag HTML <picture>.

<html>
  <head>
    <title>Animated AVIF Example</title>
  </head>
  <body>
    <picture>
      <source type="image/avif" srcset="minha_animacao.avif" />
      <img src="minha_animacao.gif" />
    </picture>
  </body>
</html>

Se o navegador tiver suporte, tentará primeiro carregar a imagem em formato AVIF; senão, carregará a imagem em formato GIF. A animação abaixo está dentro de uma tag <picture> — você pode conferir o formato ao salvar o arquivo.

Devido ao tamanho menor das imagens, as páginas carregam mais rápido.

Para ler mais

JPEG XL vs AVIF: A Comparison (WebArchive)

Image formats comparison

What’s the best lossless image format? Comparing PNG, WebP, AVIF, and JPEG XL (WebArchive)

How to compare images fairly (WebArchive)

How JPEG XL Compares to Other Image Codecs (WebArchive)

The Current Role of Image Compression Standards in Medical Imaging (WebArchive)

Serving AVIF images codelab

Fontes das imagens

Todas extraídas do Unsplash:

Links simbólicos em multi-repos

2024-01-19T00:00:00Z

Arquivos repetidos

Diga: a organização de arquivos abaixo lhe é familiar?

> tree C:\MeusProjetos\ /F

C:\MeusProjetos\
│
├──── Repo1\
│          src\
│          .editorconfig
│          lint.xml
│          build.sh
│          runtestcoverage.ps1
│          ...
│
├──── Repo2\
│          src\
│          .editorconfig
│          lint.xml
│          build.sh
│          runtestcoverage.ps1
│          ...
│
│ ...

Note que há arquivos iguais em conteúdo e com uma cópia deles em cada diretório de projeto. Alguns exemplos de arquivos repetidos são:

Arquivos de estilo de código:
- .editorconfig (várias linguagens)
- checkstyle.xml (Java, Android)
- .eslintrc (JavaScript, TypeScript)
Arquivos de scripts:
- build.sh
- runtestcoverage.ps1 (scripts gerais)
- CMakeLists.txt
- Makefile (compilação para C/C++)
- Jenkinsfile
Arquivos de segredos e configurações de execução:
- appsettings.json (.NET)
- Web.config (ASP NET Framework)
- .env (npm)
- outros

Se você tem vários repositórios com arquivos repetidos, fica cansativo alterar esses arquivos, pois o esforço precisa ser feito em cada repositório.

Ponteiros?

Em programação, existe o conceito de ponteiro — algo que aponta para outra coisa. Geralmente, associamos ponteiros a memória, algo que aponta para um valor ou estrutura na memória RAM. Porém, o conceito de ponteiros existe também em sistemas de arquivos: são os links simbólicos, symlinks, arquivos que apontam para outros arquivos.

Os links simbólicos são uma tecnologia consolidada, tendo surgido já na década de 1960. Há suporte amplo no Linux, Mac OSX e Windows, mesmo em versões mais antigas.

Ligações

Em um sistema de arquivos, cada elemento, arquivo ou pasta, é representado por um inode.

Um inode de arquivo é composto por metadados e o endereço no disco rígido. Inodes de diretórios são listas de outros inodes.

Existem dois tipos de ligações: os hardlinks e os symlinks.

Um hardlink é quando um arquivo aponta para o mesmo inode que outro arquivo. Ambos acessam o mesmo conteúdo no disco rígido. Quando um arquivo é excluído, o conteúdo do outro não é perdido.

Um symlink é quando um arquivo aponta para outro arquivo. Nesse caso, o arquivo ponteiro depende do arquivo original para acessar o conteúdo. Se o arquivo original for excluído ou mudar de local, o symlink torna-se inválido.

Symlinks podem ter caminhos absolutos ou relativos.

Exemplo de caminho absoluto: /home/alexandre/Projetos/arquivo.txt

Exemplo de caminho relativo: ../arquivo.txt

graph TD;
    I(inode)
    A(arquivo.txt)
    AHL(arquivo_hardlink.txt)
    ASL(arquivo_symlink.txt)
    A==>I
    AHL==hardlink==>I
    ASL-.symlink.->A
    style I fill:#f9f,stroke:#333,stroke-width:4px,color:#000

Symlinks para organização de arquivos

Considerando o cenário exposto no começo do artigo, podemos unificar arquivos de vários projetos, fazendo uso de symlinks.

Dentro da cada repositório, vamos criar links que apontarão para arquivos em uma pasta Configs, em um nível acima. A pasta Configs pode se tornar um repositório à parte, separado do Repo1 e do Repo2.

O diagrama abaixo exemplifica melhor. --> indica um symlink.

C:\MeusProjetos\
│
├──── Configs\
│          .editorconfig
│          build.sh
│
├──── Repo1\
│          .editorconfig --> ../Configs/.editorconfig
│          build.sh --> ../Configs/build.sh
│          ...
│
├──── Repo2\
│          .editorconfig --> ../Configs/.editorconfig
│          build.sh --> ../Configs/build.sh
│          ...
│
│ ...

No VS Code, symlinks têm uma setinha ao lado direito do nome do arquivo.

O comando para criar links simbólicos no Linux e no Mac OSX é:

ln -s ../Configs/arquivo_original.txt arquivo_symlink.txt

Na linha de comando do Windows:

REM requer elevação de Administrador
mklink arquivo_symlink.txt ..\Configs\arquivo_original.txt

No PowerShell:

# requer elevação de Administrador
New-Item -ItemType SymbolicLink -Path arquivo_symlink.txt -Value ../Configs/arquivo_original.txt

Git

O Git suporta ter arquivos symlink commitados nos repositórios.

No GitHub, eles aparecem com uma setinha e nome em azul.

Na navegação online e em pull requests, o conteúdo do arquivo aparece como um texto do caminho, absoluto ou relativo.

Quando devo usar essa abordagem?

Organizar arquivos com symlinks é bom em situações com muitos projetos, que usam vários arquivos em comum.

Se há poucos arquivos em comum, ou se há poucos repositórios, tudo bem ter arquivos replicados!

Em alguns casos, como pipelines, é melhor escolher outras abordagens de reuso. O GitHub Actions, por exemplo, sugere adotar reusable workflows.

Diretórios simbólicos podem ser uma boa alternativa a submódulos do Git.

Detalhes importantes

Se você estiver usando Windows, é necessário habilitar links simbólicos durante a instalação do Git:

Alguns sistemas de arquivos não suportam links simbólicos, por exemplo, FAT32 e exFAT. Esses sistemas de arquivos são comuns em pen-drives e cartões SD.
Symlinks são diferentes de atalhos do Windows. Estes últimos são arquivos com extensão .lnk e que são abertos apenas pelo Windows Explorer e pelo Desktop.