Referência de steps

Gerado a partir dos atributos [Step("...")] encontrados por reflection e da documentação de cada step em docs-site/data/steps/ — nunca escrito à mão. Regenere com dotnet run --project tools/docs-reference-generator depois de um dotnet build pipevine.slnx -c Release. Um step sem arquivo de documentação (ou um arquivo sem step correspondente) falha a geração — as duas fontes não conseguem divergir em silêncio.

Cobre só os steps registrados como IStepFactory — não os seis de controle de fluxo (branch, switch, foreach, parallel, try, group), que o PipelineBuilder trata como sintaxe estrutural do próprio motor. Ver Controle de fluxo.

Visão geral

`type:`	Publica	Provider(s)	O que faz
`cache.get`	`steps.<id>.result`	caches (qualquer)	Lê uma chave do cache e publica o valor (ou `null` no miss).
`cache.invalidate`	—	caches (qualquer)	Remove do cache por chave ou por tag.
`cache.set`	—	caches (qualquer)	Grava uma chave no cache, com TTL e tags.
`cassandra.persist`	—	cassandra	Escrita no Cassandra com `ttl`, `consistency` e `ifNotExists`.
`cassandra.query`	`steps.<id>.result`	cassandra	Consulta no Cassandra com `consistency` e paginação por cursor nativa.
`db.delete`	—	dataSources (qualquer)	Remove o registro casado pela chave declarada da entidade.
`db.exists`	`steps.<id>.result`	dataSources (qualquer)	Booleano indicando se existe registro casando `where`.
`db.find`	`steps.<id>.result`	dataSources (qualquer)	Uma entidade casando `where`, ou `null`.
`db.persist`	—	dataSources (qualquer)	Insere (ou faz upsert) o objeto produzido por `data` na entidade.
`db.query`	`steps.<id>.result`	dataSources (qualquer)	Lista de registros casando `where`, com ordenação e paginação opcionais.
`db.sql`	—	dataSources (qualquer)	Escape hatch para SQL que os steps `db.*` estruturados não expressam.
`db.update`	—	dataSources (qualquer)	Atualização parcial, casando pela chave declarada da entidade.
`dynamo.persist`	—	dynamodb	Escrita no DynamoDB com `condition` (ConditionExpression).
`dynamo.query`	`steps.<id>.result`	dynamodb	Consulta no DynamoDB com índice explícito e cursor nativo.
`fail`	—	—	Interrompe o pipeline com um erro estruturado.
`grpc.call`	`steps.<id>.result`	integração	Chama uma integração gRPC declarada em `spec.integrations`.
`http.call`	`steps.<id>.result`	integração	Chama uma integração HTTP declarada em `spec.integrations`.
`log`	—	—	Emite uma linha de log estruturada.
`map`	—	—	Avalia uma expressão JSONata e grava o resultado sob `vars`.
`noop`	—	—	Não faz nada.
`publish`	—	brokers (qualquer)	Publica um evento declarado em `spec.events`.
`return`	—	—	Interrompe o pipeline com sucesso, definindo `output`.
`set`	—	—	Atribui um valor literal a um caminho sob `vars`.
`storage.delete`	—	storages (qualquer)	Remove um objeto por chave.
`storage.get`	`steps.<id>.result`	storages (qualquer)	Transmite o objeto direto na resposta HTTP, em streaming.
`storage.list`	`steps.<id>.result`	storages (qualquer)	Lista objetos por prefixo de chave.
`storage.presignDownload`	`steps.<id>.result`	storages (qualquer)	Gera uma URL para o cliente baixar o arquivo direto do backend.
`storage.presignUpload`	`steps.<id>.result`	storages (qualquer)	Gera uma URL para o cliente subir o arquivo direto no backend.
`storage.put`	`steps.<id>.result`	storages (qualquer)	Grava o corpo da requisição HTTP direto no backend, em streaming.
`storage.stat`	`steps.<id>.result`	storages (qualquer)	Metadados de um objeto, sem baixar o conteúdo.
`validate`	—	—	Valida a forma (JSON Schema) e/ou as regras de negócio (JSONata) da entrada.

Detalhes por step

`cache.get`

Classe: Pipevine.Caching.Abstractions.Steps.GetStepFactory · Pacote: Pipevine.Caching.Abstractions

Provider(s): Qualquer provider registrado em spec.caches que implemente ICacheProvider, ver ICacheProvider.

Lê key do cache declarado e publica o valor encontrado.

Um miss não é falha: publica null e o pipeline segue — inclusive o miss produzido pelo comportamento fail-open, quando o backend de cache está indisponível. Do ponto de vista do pipeline, cache frio e cache fora do ar são a mesma coisa, de propósito.

- { type: cache.get, id: cached, cache: redis-main, key: "'order:' & input.route.orderId" }

Publica em steps.<id>.result: O valor cacheado, ou null no miss.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`cache_get_failed`	A expressão `key` falhou ao ser avaliada. (Indisponibilidade do backend vira miss, não falha.)	500	—

`cache.invalidate`

Classe: Pipevine.Caching.Abstractions.Steps.InvalidateStepFactory · Pacote: Pipevine.Caching.Abstractions

Provider(s): Qualquer provider registrado em spec.caches que implemente ICacheProvider, ver ICacheProvider.

Remove por key (uma expressão JSONata) ou por tag (uma string literal) — exatamente um dos dois, nunca os dois juntos.

Invalidar por tag apaga todas as entradas gravadas com aquela tag, o que é a forma de expirar um grupo inteiro depois de uma escrita.

- { type: cache.invalidate, cache: redis-main, tag: orders }

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`cache_invalidate_failed`	A expressão `key` falhou ao ser avaliada.	500	—

`cache.set`

Classe: Pipevine.Caching.Abstractions.Steps.SetStepFactory · Pacote: Pipevine.Caching.Abstractions

Provider(s): Qualquer provider registrado em spec.caches que implemente ICacheProvider, ver ICacheProvider.

Grava value sob key. ttl é a expiração absoluta e slidingTtl reinicia a cada acesso — ambos opcionais. As tags são o que permite invalidar um grupo inteiro depois, com o cache.invalidate.

Não publica resultado.

- type: cache.set
  cache: redis-main
  key: "'order:' & vars.order.id"
  value: vars.order
  ttl: 5m
  tags: [orders]

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`cache_set_failed`	A expressão `key` ou `value` falhou ao ser avaliada.	500	—

`cassandra.persist`

Classe: Pipevine.Data.Cassandra.Steps.CassandraPersistStepFactory · Pacote: Pipevine.Data.Cassandra

Provider(s): Específico do(s) provider(s) cassandra — não roda contra nenhum outro.

Tudo que o db.persist não expressa para Cassandra: expiração ttl nativa por linha, nível de consistency por escrita, e ifNotExists — uma lightweight transaction (INSERT ... IF NOT EXISTS), que é a única forma de fazer valer unicidade neste provider.

Se você precisa de unicidade no Cassandra, é este step, não o db.persist com onConflict — que ali não tem efeito.

- type: cassandra.persist
  entity: OrderEvent
  data: vars.order
  ttl: "3600"
  consistency: local_quorum
  ifNotExists: true

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`cassandra_persist_failed`	A expressão `data` avaliou para `null`.	500	—
`cassandra_persist_failed`	A escrita falhou no Cassandra.	500	—

`cassandra.query`

Classe: Pipevine.Data.Cassandra.Steps.CassandraQueryStepFactory · Pacote: Pipevine.Data.Cassandra

Provider(s): Específico do(s) provider(s) cassandra — não roda contra nenhum outro.

Tudo que o db.query não expressa para Cassandra: nível de consistency por consulta, paginação nativa por cursor (pageSize/pageState — nunca skip:, que este provider não suporta) e um allowFiltering explícito no próprio step, independente do que a entidade declara.

Publica um objeto estruturado, não um array puro, porque tem uma segunda coisa a reportar que o db.query não tem: o cursor da próxima página.

- type: cassandra.query
  id: events
  entity: OrderEvent
  where: { customerId: "input.route.id" }
  sort: ["-createdAt"]
  consistency: local_quorum
  pageSize: 50
  pageState: "input.query.cursor"
  allowFiltering: false

Publica em steps.<id>.result: { items: [...], pageState: "<cursor ou null>" } — pageState é null na última página.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`cassandra_query_failed`	A consulta falhou no Cassandra.	500	—

`db.delete`

Classe: Pipevine.Data.Abstractions.Steps.DeleteStepFactory · Pacote: Pipevine.Data.Abstractions

Provider(s): Qualquer provider registrado em spec.dataSources que implemente IDataProvider — o suporte a cada capacidade (paginação por cursor, upsert, etc.) varia por provider, ver IDataProvider e a tabela de Capabilities.

Remove o registro localizado pela chave declarada da entidade, cujo valor vem da expressão em key. Como no db.update, não há where:.

Remover uma chave inexistente não é erro — o step continua normalmente.

- type: db.delete
  entity: order
  key: input.route.id

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`db_delete_failed`	A remoção falhou no banco.	500	—

`db.exists`

Classe: Pipevine.Data.Abstractions.Steps.ExistsStepFactory · Pacote: Pipevine.Data.Abstractions

Publica true/false conforme exista ou não um registro casando where. Mais barato que um db.find quando você só precisa saber se existe — não traz o registro.

- { type: db.exists, id: dup, entity: Order, where: { id: "input.body.id" } }

Publica em steps.<id>.result: Um booleano.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`db_exists_failed`	A consulta falhou no banco.	500	—

`db.find`

Classe: Pipevine.Data.Abstractions.Steps.FindStepFactory · Pacote: Pipevine.Data.Abstractions

Busca um registro pelos campos de where (sempre igualdade por campo) e publica o resultado.

Não encontrar não é falha: publica null e o pipeline segue. O padrão para transformar isso num 404 é o step seguinte — { type: fail, when: "steps.<id>.result = null", status: 404, ... }.

- { type: db.find, id: customer, entity: Customer, where: { id: "input.body.customerId" } }

Publica em steps.<id>.result: O registro encontrado, ou null quando nada casa.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`db_find_failed`	A consulta falhou no banco.	500	—

`db.persist`

Classe: Pipevine.Data.Abstractions.Steps.PersistStepFactory · Pacote: Pipevine.Data.Abstractions

Insere o objeto que data produzir na tabela/coleção da entidade. Com onConflict declarado, vira um upsert pelas colunas indicadas.

Não publica resultado: se você precisa do registro gravado adiante no pipeline, use o próprio vars.<algo> que alimentou o data.

- type: db.persist
  entity: order
  data: vars.order
  onConflict: { columns: [id] }   # opcional — sem isso é um insert puro

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`db_persist_failed`	A expressão `data` avaliou para `null`.	500	—
`db_persist_failed`	A escrita no banco falhou.	500	—

`db.query`

Classe: Pipevine.Data.Abstractions.Steps.QueryStepFactory · Pacote: Pipevine.Data.Abstractions

Lista os registros que casam where, com sort opcional (nomes de campo, prefixados por - para descendente) e skip/take — que são expressões JSONata, então a paginação pode vir da própria requisição.

skip: exige que o provider declare a capacidade OffsetPaging. Providers cursor-only (Cassandra, DynamoDB) falham o build nomeando a limitação e apontando para o step de paginação próprio deles (cassandra.query, dynamo.query) — não é um erro que aparece só em produção.

Publica sempre um array; nenhum resultado é um array vazio, não null.

- type: db.query
  id: list
  entity: Order
  where: { customerId: "input.query.customerId" }
  sort: [ "-createdAt" ]
  skip: "input.query.skip"
  take: "input.query.take"

Publica em steps.<id>.result: Um array dos registros casados — vazio quando nada casa.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`db_query_failed`	A consulta falhou no banco.	500	—

`db.sql`

Classe: Pipevine.Data.Abstractions.Steps.SqlStepFactory · Pacote: Pipevine.Data.Abstractions

Aponta para um dataSource (não para uma entity) e executa o SQL declarado.

Os valores de params são expressões JSONata, compiladas no build e avaliadas por requisição — e ligadas como parâmetros ADO.NET reais pelo provider, nunca interpoladas no texto do SQL. É isso que faz um valor como '; DROP TABLE orders; -- ser dado comum em vez de injeção: o texto do SQL é fixo desde o build e jamais toca os valores avaliados.

Só existe para providers que declaram a capacidade RawStatements — num provider sem dialeto SQL (MongoDB, por exemplo) o build falha nomeando a limitação, em vez de quebrar em runtime.

Não publica resultado.

- type: db.sql
  dataSource: main
  sql: "DELETE FROM legacy_orders WHERE customer_id = @customerId"
  params:
    customerId: input.body.customerId

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`db_sql_failed`	A execução do comando falhou no banco.	500	—

`db.update`

Classe: Pipevine.Data.Abstractions.Steps.UpdateStepFactory · Pacote: Pipevine.Data.Abstractions

Faz merge de patch com o registro existente, localizado pela chave declarada da entidade — cujo valor vem da expressão em key. Não existe where: neste step: quem filtra por outros campos é o db.query.

- type: db.update
  entity: order
  key: input.route.id
  patch: vars.patch

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`db_update_failed`	A expressão `patch` avaliou para `null`.	500	—
`db_update_failed`	A escrita no banco falhou.	500	—

`dynamo.persist`

Classe: Pipevine.Data.DynamoDb.Steps.DynamoPersistStepFactory · Pacote: Pipevine.Data.DynamoDb

Provider(s): Específico do(s) provider(s) dynamodb — não roda contra nenhum outro.

Tudo que o db.persist não expressa para DynamoDB: condition, uma ConditionExpression crua, que é como se faz concorrência otimista e unicidade real neste provider (attribute_not_exists(id)).

Uma condição não satisfeita levanta ConditionalCheckFailedException no commit — este step não esconde isso. Se você quer tratar a colisão como regra de negócio, envolva num try/catch.

- type: dynamo.persist
  entity: OrderEvent
  data: vars.order
  condition: "attribute_not_exists(id)"

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`dynamo_persist_failed`	A expressão `data` avaliou para `null`.	500	—
`dynamo_persist_failed`	A escrita falhou no DynamoDB.	500	—

`dynamo.query`

Classe: Pipevine.Data.DynamoDb.Steps.DynamoQueryStepFactory · Pacote: Pipevine.Data.DynamoDb

Provider(s): Específico do(s) provider(s) dynamodb — não roda contra nenhum outro.

Tudo que o db.query não expressa para DynamoDB: um GSI/LSI explícito (index: — nunca inferido), consistentRead, projeção de atributos, e cursor nativo (exclusiveStartKey/lastEvaluatedKey) no lugar de skip:.

É sempre um Query, nunca um Scan: o sentido deste step é que quem chama já sabe qual índice quer atingir.

Como o cassandra.query, publica um objeto estruturado por causa do cursor.

- type: dynamo.query
  id: events
  entity: OrderEvent
  index: byStatus
  where: { status: "input.query.status" }
  sort: ["-createdAt"]
  consistentRead: false
  projection: ["id", "status", "createdAt"]
  exclusiveStartKey: "input.query.cursor"
  take: "50"

Publica em steps.<id>.result: { items: [...], lastEvaluatedKey: "<cursor ou null>" } — null na última página.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`dynamo_query_failed`	A consulta falhou no DynamoDB.	500	—

`fail`

Classe: Pipevine.Core.Steps.FailStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Interrompe a execução com um erro que você mesmo define. É como se expressa uma regra de negócio que impede continuar — tipicamente combinado com when.

code é obrigatório e é o valor que a tabela errors: da rota casa. message assume o próprio code quando omitido. status é opcional, mas omiti-lo não significa "deixa o framework escolher": sem status aqui e sem uma entrada em errors: que case, a resposta é 500.

- type: fail
  when: "steps.customer.result = null"
  status: 404
  code: CUSTOMER_NOT_FOUND
  message: "cliente não encontrado"

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`<definido por você em code:>`	Sempre que o step executa — é o propósito dele.	O valor de `status:`; sem ele, `500`.	O conteúdo de `details:`, quando declarado.

`grpc.call`

Classe: Pipevine.Integrations.Grpc.Steps.GrpcCallStepFactory · Pacote: Pipevine.Integrations.Grpc

Provider(s): Não é um step de provider de dados — chama a integração declarada em spec.integrations, com a política de resiliência dela.

Mesma forma e mesmo contrato de fallback do http.call, sobre uma integração de kind: grpc.

mode: typed usa o cliente gerado do .proto (via clientType); mode: dynamic monta a chamada a partir de requestType/responseType. O default é typed.

Como no http.call: um status OK publica o corpo em steps.<id>.result e só se id: existir; um status não-OK que sobreviveu à resiliência aciona resilience.fallback quando declarado.

- type: grpc.call
  id: quote
  integration: pricing-grpc
  mode: typed                 # typed | dynamic (default: typed)
  service: pricing.PricingService
  method: GetQuote
  clientType: "Pricing.PricingService+PricingServiceClient, PricingContracts"   # modo typed
  request: "{ 'sku': vars.sku }"

Publica em steps.<id>.result: O corpo da resposta num status OK, ou o valor de resilience.fallback.expr quando o fallback por expressão rodou. Um fallback em sub-pipeline não publica aqui.

Sem id: o resultado é descartado em silêncio — nenhum erro avisa.

Falhas:

`code`	Quando	`status`	`details`
`grpc_call_failed`	A chamada retornou um status gRPC não-OK que sobreviveu à resiliência, sem `fallback`.	502	—
`grpc_call_failed`	Timeout, circuito aberto ou falha de transporte, sem `fallback` declarado.	502	—
`grpc_call_failed`	A expressão `request` falhou ao ser avaliada.	500	—
`grpc_call_fallback_failed`	A expressão do próprio `resilience.fallback` falhou ao ser avaliada.	500	—

`http.call`

Classe: Pipevine.Integrations.Http.Steps.HttpCallStepFactory · Pacote: Pipevine.Integrations.Http

Provider(s): Não é um step de provider de dados — chama a integração declarada em spec.integrations, com a política de resiliência dela.

Chama a integração nomeada em integration, com method/path, e um body/headers produzidos por expressões JSONata.

Onde o resultado fica depende do que aconteceu, e os três casos não são o mesmo lugar:

2xx — publica em steps.<id>.result, e o que é publicado é apenas o corpo da resposta: não há status nem headers ali. Se você não declarar id:, a resposta é descartada em silêncio.
4xx — não publica nada. O step falha com http_call_failed, carregando o status do upstream, e o corpo da resposta vai para os details da falha — que sai no details da resposta ProblemDetails, não em steps.<id>.result. Um 4xx nunca é retentado nem aciona fallback: significa que a requisição foi rejeitada, não que a integração está doente.
≥500, ou falha de transporte (timeout, circuito aberto) — se a integração declarar resilience.fallback, ele roda. Com fallback.expr, o valor da expressão é publicado em steps.<id>.result, como se fosse um sucesso. Com fallback em sub-pipeline, nada é publicado em steps.<id>.result — os steps de dentro gravam os próprios resultados. Sem fallback declarado, o step falha: 502 para falha de transporte, e o próprio status do upstream (503, 504, ...) quando foi ele quem respondeu 5xx.

Para a rota não devolver 500 nesses casos, veja Tratamento de erros: ou um resilience.fallback na integração, ou uma entrada errors: casando http_call_failed, ou um try/catch em volta.

- type: http.call
  id: price
  integration: pricing
  method: POST
  path: /quote
  body: "{ 'items': vars.order.items }"
  headers: { X-Correlation-Id: "input.headers.'x-correlation-id'" }

Publica em steps.<id>.result: Só o corpo da resposta (sem status, sem headers) num 2xx; ou o valor de resilience.fallback.expr quando o fallback por expressão rodou. Um fallback em sub-pipeline não publica aqui.

Sem id: o resultado é descartado em silêncio — nenhum erro avisa.

Falhas:

`code`	Quando	`status`	`details`
`http_call_failed`	O upstream respondeu 4xx (nunca aciona `fallback`).	O status do upstream	O corpo da resposta
`http_call_failed`	O upstream respondeu 5xx e não havia `fallback` declarado.	O status do upstream	O corpo da resposta
`http_call_failed`	Timeout, circuito aberto ou falha de transporte, sem `fallback` declarado.	502	—
`http_call_failed`	A expressão `body` ou de um `header` falhou ao ser avaliada.	500	—
`http_call_fallback_failed`	A expressão do próprio `resilience.fallback` falhou ao ser avaliada.	500	—

`log`

Classe: Pipevine.Core.Steps.LogStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Registra message com os fields declarados, e sempre continua.

message e os valores de fields são literais: não são avaliados como JSONata. Escrever message: "'erro: ' & error.message" não interpola nada — registra esse texto exatamente como está. Não há como, hoje, incluir um valor do estado do pipeline numa linha de log.

- type: log
  message: "processando pedido"
  fields:
    etapa: "validacao"

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

`map`

Classe: Pipevine.Core.Steps.MapStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Avalia expr sobre o estado atual do pipeline e grava o resultado em to. É o step de transformação: converte o payload recebido no formato que a persistência, a resposta ou o evento publicado precisam.

to precisa começar com vars. — qualquer outro destino é recusado no build.

- type: map
  to: vars.order
  expr: |
    { "id": $uuid(), "total": $sum(input.body.items.(price * quantity)) }

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`map_failed`	A expressão falhou ao ser avaliada em runtime.	500	—

`noop`

Classe: Pipevine.Core.Steps.NoopStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Não faz nada e sempre continua. Útil como placeholder ao montar um pipeline aos poucos, e em testes que precisam de um step sem efeito colateral.

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

`publish`

Classe: Pipevine.Messaging.Abstractions.Steps.PublishStepFactory · Pacote: Pipevine.Messaging.Abstractions

Provider(s): Qualquer provider registrado em spec.brokers que implemente IMessageProvider, ver IMessageProvider.

Publica o evento nomeado em event (uma entrada de spec.events), com o corpo produzido pela expressão payload.

mode: direct publica no broker de forma síncrona. mode: outbox grava a mensagem de forma durável dentro da mesma transação da rota, e um despachante em segundo plano entrega depois, pelo menos uma vez — o que exige transaction: required na rota/consumer. Sem isso, o build falha nomeando a exigência; não é um erro que aparece só em produção.

Não publica resultado no estado do pipeline.

- type: publish
  event: OrderCreated
  payload: vars.order
  mode: outbox        # direct | outbox

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`publish_failed`	A expressão `payload` avaliou para `null`.	500	—
`publish_failed`	A publicação no broker falhou.	500	—

`return`

Classe: Pipevine.Core.Steps.ReturnStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Encerra o pipeline com sucesso, gravando output como resultado da execução — o que vira o corpo da resposta HTTP (ou a mensagem, num consumer). Os steps seguintes não rodam.

Diferente do fail, não é uma condição de erro: a rota responde normalmente, com o status de sucesso declarado em response.status.

- type: return
  output:
    total: 42

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

`set`

Classe: Pipevine.Core.Steps.SetStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

Grava um valor literal — não uma expressão — em target. Para calcular o valor a partir do estado do pipeline, use o map.

O valor é clonado a cada execução, então uma estrutura declarada aqui nunca é compartilhada entre requisições concorrentes.

- type: set
  target: vars.total
  value: 12

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

`storage.delete`

Classe: Pipevine.Storage.Abstractions.Steps.DeleteStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Remove o objeto sob key. Remover uma chave inexistente não é erro.

Sem fail-open: uma indisponibilidade do backend derruba a requisição, ao contrário do cache. Storage é dado, não otimização.

- { type: storage.delete, storage: docs, key: input.route.key }

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`storage_delete_failed`	A expressão `key` falhou, ou a remoção falhou no backend.	500	—

`storage.get`

Classe: Pipevine.Storage.Abstractions.Steps.GetStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Transmite o conteúdo do objeto direto para o corpo da resposta HTTP, sem nunca materializá-lo como JsonNode. O que vai para steps.<id>.result são só os metadados — o conteúdo não passa pelo estado do pipeline.

Objeto inexistente não é falha: publica null, e o padrão para virar 404 é o mesmo do db.find — um fail com when no step seguinte.

Só existe em spec.type: api, pelo mesmo motivo do storage.put.

- { type: storage.get, id: get, storage: docs, key: input.route.key }

Publica em steps.<id>.result: Os metadados do objeto (key, size, contentType, etag, lastModified), ou null se não existe.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_get_failed`	A expressão `key` falhou, ou a leitura falhou no backend.	500	—

`storage.list`

Classe: Pipevine.Storage.Abstractions.Steps.ListStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Lista os objetos cuja chave começa com prefix, paginando internamente quando o backend limita a quantidade por chamada — o pipeline recebe a lista completa, não a primeira página.

- { type: storage.list, id: files, storage: docs, prefix: "'docs/'" }

Publica em steps.<id>.result: Um array de { key, size, lastModified } — vazio quando nada casa o prefixo.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_list_failed`	A expressão `prefix` falhou, ou a listagem falhou no backend.	500	—

`storage.presignDownload`

Classe: Pipevine.Storage.Abstractions.Steps.PresignDownloadStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

O espelho do storage.presignUpload: gera uma URL temporária com a qual o cliente baixa direto do backend, sem o corpo passar pela sua API.

ttl é obrigatório. Gerar a URL não verifica se o objeto existe — use storage.stat antes se precisar dessa garantia.

- { type: storage.presignDownload, id: download, storage: docs, key: input.route.key, ttl: 5m }

Publica em steps.<id>.result: { key, url, expiresAt } — expiresAt é uma string ISO-8601.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_presign_download_failed`	A expressão `key` falhou, ou o backend não gerou a URL.	500	—

`storage.presignUpload`

Classe: Pipevine.Storage.Abstractions.Steps.PresignUploadStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Gera uma URL temporária com a qual o cliente faz o upload direto no backend — o corpo do arquivo nunca passa pela sua API. É a alternativa ao storage.put quando você não quer o tráfego atravessando o processo.

ttl é obrigatório e define por quanto tempo a URL vale. Funciona em qualquer tipo de aplicação (é operação de metadata), inclusive num consumer.

- { type: storage.presignUpload, id: upload, storage: docs, key: "'docs/' & $uuid()", ttl: 5m, contentType: input.body.contentType }

Publica em steps.<id>.result: { key, url, expiresAt } — expiresAt é uma string ISO-8601.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_presign_upload_failed`	A expressão `key` falhou, ou o backend não gerou a URL.	500	—

`storage.put`

Classe: Pipevine.Storage.Abstractions.Steps.PutStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Transmite o corpo da requisição HTTP direto para o storage, sem nunca materializá-lo como JsonNode — é assim que um upload grande não passa pela memória do processo.

Só existe em spec.type: api. Dentro do pipeline de um consumer é recusado no build, porque ali não existe corpo de requisição HTTP para transmitir.

- { type: storage.put, id: put, storage: docs, key: input.route.key }

Publica em steps.<id>.result: { key, size, etag } do objeto gravado.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_put_failed`	A expressão `key` falhou, ou a gravação falhou no backend.	500	—

`storage.stat`

Classe: Pipevine.Storage.Abstractions.Steps.StatStepFactory · Pacote: Pipevine.Storage.Abstractions

Provider(s): Qualquer provider registrado em spec.storages que implemente IStorageProvider, ver IStorageProvider.

Lê os metadados do objeto sob key sem transferir o conteúdo — é a forma barata de checar existência e tamanho, tipicamente depois de um upload por URL pré-assinada.

Objeto inexistente publica null, não falha.

- { type: storage.stat, id: meta, storage: docs, key: input.route.key }

Publica em steps.<id>.result: Os metadados do objeto (key, size, contentType, etag, lastModified), ou null se não existe.

id: é obrigatório neste step — sem ele o build falha.

Falhas:

`code`	Quando	`status`	`details`
`storage_stat_failed`	A expressão `key` falhou, ou a leitura falhou no backend.	500	—

`validate`

Classe: Pipevine.Core.Steps.ValidateStepFactory · Pacote: Pipevine.Core

Provider(s): Não aplicável — step do motor de pipeline (Pipevine.Core), não depende de nenhum provider.

schema valida a forma do dado; rules valida regra de negócio. Os dois são opcionais, mas pelo menos um precisa existir — e não se usa os dois para a mesma preocupação.

mode é obrigatório: collect avalia todas as regras e reporta todas as violações de uma vez; failFast para na primeira. Não há default — omitir mode falha o build.

- type: validate
  mode: collect                # collect | failFast
  schema: { type: object, required: [customerId] }
  rules:
    - { expr: "$count(input.body.items) > 0", code: EMPTY_ORDER, path: /items, message: "pedido sem itens" }

Não publica resultado. Declarar id: neste step é aceito e não tem efeito nenhum.

Falhas:

`code`	Quando	`status`	`details`
`validation_failed`	Alguma regra ou o schema foi violado.	400	Uma lista de `{ code, path, message }`, uma entrada por violação. A camada HTTP a converte num `ValidationProblemDetails` agrupado por `path`.

Catálogo de códigos de erro

Todo código que uma execução de pipeline pode produzir. É por estes valores que a tabela errors: de uma rota faz o casamento — { code: <um destes>, status: ..., title: ... }. Ver Tratamento de erros para como usá-los.

Uma entrada de errors: que casa sempre impõe o próprio status:, e omiti-lo vale 500 — o status da coluna abaixo é o que a falha carrega quando nenhuma entrada casa.

`code`	Origem	Quando	`status`	Remapeável por `errors:`
`<definido por você em code:>`	`fail`	Sempre que o step executa — é o propósito dele.	O valor de `status:`; sem ele, `500`.	sim
`binding_failed`	binding da requisição	Header ou parâmetro de query obrigatório ausente, ou corpo JSON malformado. Acontece antes do pipeline, então nenhum step chega a rodar.	400	não
`branch_failed`	`branch`	A expressão `when` do próprio `branch` falhou ao ser avaliada.	500	sim
`cache_get_failed`	`cache.get`	A expressão `key` falhou ao ser avaliada. (Indisponibilidade do backend vira miss, não falha.)	500	sim
`cache_invalidate_failed`	`cache.invalidate`	A expressão `key` falhou ao ser avaliada.	500	sim
`cache_set_failed`	`cache.set`	A expressão `key` ou `value` falhou ao ser avaliada.	500	sim
`cassandra_persist_failed`	`cassandra.persist`	A expressão `data` avaliou para `null`.	500	sim
`cassandra_persist_failed`	`cassandra.persist`	A escrita falhou no Cassandra.	500	sim
`cassandra_query_failed`	`cassandra.query`	A consulta falhou no Cassandra.	500	sim
`db_delete_failed`	`db.delete`	A remoção falhou no banco.	500	sim
`db_exists_failed`	`db.exists`	A consulta falhou no banco.	500	sim
`db_find_failed`	`db.find`	A consulta falhou no banco.	500	sim
`db_persist_failed`	`db.persist`	A expressão `data` avaliou para `null`.	500	sim
`db_persist_failed`	`db.persist`	A escrita no banco falhou.	500	sim
`db_query_failed`	`db.query`	A consulta falhou no banco.	500	sim
`db_sql_failed`	`db.sql`	A execução do comando falhou no banco.	500	sim
`db_update_failed`	`db.update`	A expressão `patch` avaliou para `null`.	500	sim
`db_update_failed`	`db.update`	A escrita no banco falhou.	500	sim
`dynamo_persist_failed`	`dynamo.persist`	A expressão `data` avaliou para `null`.	500	sim
`dynamo_persist_failed`	`dynamo.persist`	A escrita falhou no DynamoDB.	500	sim
`dynamo_query_failed`	`dynamo.query`	A consulta falhou no DynamoDB.	500	sim
`forbidden`	autorização	Autenticado, mas sem o escopo/papel/claim exigido, ou o `authorize.expr` avaliou falso.	403	não
`foreach_failed`	`foreach`	A expressão `in` (ou a de `collect.select`) falhou ao ser avaliada.	500	sim
`grpc_call_failed`	`grpc.call`	A chamada retornou um status gRPC não-OK que sobreviveu à resiliência, sem `fallback`.	502	sim
`grpc_call_failed`	`grpc.call`	Timeout, circuito aberto ou falha de transporte, sem `fallback` declarado.	502	sim
`grpc_call_failed`	`grpc.call`	A expressão `request` falhou ao ser avaliada.	500	sim
`grpc_call_fallback_failed`	`grpc.call`	A expressão do próprio `resilience.fallback` falhou ao ser avaliada.	500	sim
`http_call_failed`	`http.call`	O upstream respondeu 4xx (nunca aciona `fallback`).	O status do upstream	sim
`http_call_failed`	`http.call`	O upstream respondeu 5xx e não havia `fallback` declarado.	O status do upstream	sim
`http_call_failed`	`http.call`	Timeout, circuito aberto ou falha de transporte, sem `fallback` declarado.	502	sim
`http_call_failed`	`http.call`	A expressão `body` ou de um `header` falhou ao ser avaliada.	500	sim
`http_call_fallback_failed`	`http.call`	A expressão do próprio `resilience.fallback` falhou ao ser avaliada.	500	sim
`map_failed`	`map`	A expressão falhou ao ser avaliada em runtime.	500	sim
`publish_failed`	`publish`	A expressão `payload` avaliou para `null`.	500	sim
`publish_failed`	`publish`	A publicação no broker falhou.	500	sim
`storage_delete_failed`	`storage.delete`	A expressão `key` falhou, ou a remoção falhou no backend.	500	sim
`storage_get_failed`	`storage.get`	A expressão `key` falhou, ou a leitura falhou no backend.	500	sim
`storage_list_failed`	`storage.list`	A expressão `prefix` falhou, ou a listagem falhou no backend.	500	sim
`storage_presign_download_failed`	`storage.presignDownload`	A expressão `key` falhou, ou o backend não gerou a URL.	500	sim
`storage_presign_upload_failed`	`storage.presignUpload`	A expressão `key` falhou, ou o backend não gerou a URL.	500	sim
`storage_put_failed`	`storage.put`	A expressão `key` falhou, ou a gravação falhou no backend.	500	sim
`storage_stat_failed`	`storage.stat`	A expressão `key` falhou, ou a leitura falhou no backend.	500	sim
`switch_failed`	`switch`	A expressão `when` de um `case` falhou ao ser avaliada.	500	sim
`unauthorized`	autenticação	Token ausente, expirado, ou com issuer/audience/assinatura inválidos.	401	não
`validation_failed`	`validate`	Alguma regra ou o schema foi violado.	400	sim
`when_failed`	`when` universal	A expressão `when` de qualquer step falhou ao ser avaliada.	500	sim