output

Documentation

Overview

blocks/output/output.go

Package output provides declarative constructors for flow step responses and outbound REST API payloads. It bridges the flow pipeline with the server and restapi blocks without requiring the user to write manual JSON marshalling or request construction in every step.

All functions are pure utilities — no core.Block registration required.

Response constructors

Used as the fn argument to flow.NewStep when building the final HTTP response:

flow.NewStep("respond", output.JSON(http.StatusCreated, "payload"))
flow.NewStep("respond", output.JSONFrom(http.StatusOK, func(s *flow.State, _ *server.Request) any {
    var u User
    s.Bind("load-user", &u)
    return u
}))

REST payload builder

Used inside flow.EnrichStep to call a downstream REST API using data from the current state and request:

flow.EnrichStep("call-downstream",
    output.Call(downstreamAPI,
        output.REST("POST", "/orders").
            BodyFromState("payload").
            HeaderFromRequest("X-Trace-Id"),
    ))

Index

• func Call(api *restapi.Block, payload *Payload) func(context.Context, *server.Request, *flow.State) (any, error)
• func CallJSON(api *restapi.Block, dest any, payload *Payload) func(context.Context, *server.Request, *flow.State) (any, error)
• func Created(stateKey string) flow.StepFn
• func JSON(statusCode int, stateKey string) flow.StepFn
• func JSONFrom(statusCode int, fn func(*flow.State, *server.Request) any) flow.StepFn
• func NoContent() flow.StepFn
• func OK(stateKey string) flow.StepFn
• func Redirect(code int, urlFn func(*flow.State, *server.Request) string) flow.StepFn
• func Text(statusCode int, stateKey string) flow.StepFn
• type Payload
  • func REST(method, path string) *Payload
  • func (p *Payload) Body(value any) *Payload
  • func (p *Payload) BodyFrom(fn func(*flow.State, *server.Request) any) *Payload
  • func (p *Payload) BodyFromState(stateKey string) *Payload
  • func (p *Payload) Build(req *server.Request, state *flow.State) (restapi.Request, error)
  • func (p *Payload) Header(key, value string) *Payload
  • func (p *Payload) HeaderFrom(key string, fn func(*flow.State, *server.Request) string) *Payload
  • func (p *Payload) HeaderFromRequest(headerName string) *Payload
  • func (p *Payload) HeaderFromRequestAs(destKey, srcHeader string) *Payload
  • func (p *Payload) PathParamFromRequest(placeholder, requestParam string) *Payload
  • func (p *Payload) PathParamFromState(placeholder, stateKey, field string) *Payload
  • func (p *Payload) Query(key, value string) *Payload
  • func (p *Payload) QueryFrom(key string, fn func(*flow.State, *server.Request) string) *Payload

Functions

func Call

func Call(api *restapi.Block, payload *Payload) func(context.Context, *server.Request, *flow.State) (any, error)

Call returns a flow.EnrichStep function that builds the REST request using the Payload builder, calls the API, and stores the raw response bytes in state under the step name.

The result is a *restapi.Response. To deserialise it, use state.Bind in the next step, or use CallJSON which deserialises directly.

flow.EnrichStep("call-credit",
    output.Call(creditAPI,
        output.REST("GET", "/credit/{tax_id}").
            PathParamFromState("tax_id", "load-customer", "tax_id").
            HeaderFromRequest("X-Trace-Id"),
    ))

func CallJSON

func CallJSON(api *restapi.Block, dest any, payload *Payload) func(context.Context, *server.Request, *flow.State) (any, error)

CallJSON is like Call but immediately deserialises the response body into dest (which should be a pointer to a struct or map). The deserialised value is what gets stored in state.

var credit CreditResponse
flow.EnrichStep("load-credit",
    output.CallJSON(creditAPI, &credit,
        output.REST("GET", "/credit/{tax_id}").
            PathParamFromState("tax_id", "load-customer", "tax_id"),
    ))

func Created

func Created(stateKey string) flow.StepFn

Created is a shorthand for JSON(201, stateKey).

flow.NewStep("respond", output.Created("order"))

func JSON

func JSON(statusCode int, stateKey string) flow.StepFn

JSON returns a StepFn that reads the value at stateKey and responds with it JSON-encoded at the given status code.

flow.NewStep("respond", output.JSON(http.StatusOK, "payload"))

func JSONFrom

func JSONFrom(statusCode int, fn func(*flow.State, *server.Request) any) flow.StepFn

JSONFrom returns a StepFn that calls fn to build the response body. Use this when the response body is derived from multiple state keys or requires light transformation before serialisation.

flow.NewStep("respond",
    output.JSONFrom(http.StatusOK, func(s *flow.State, req *server.Request) any {
        var customer Customer
        s.Bind("load-customer", &customer)
        return map[string]any{
            "id":    customer.ID,
            "name":  customer.Name,
            "route": req.PathParam("id"),
        }
    }))

func NoContent

func NoContent() flow.StepFn

NoContent returns a StepFn that responds with HTTP 204 No Content.

flow.NewStep("respond", output.NoContent())

func OK

func OK(stateKey string) flow.StepFn

OK is a shorthand for JSON(200, stateKey).

func Redirect

func Redirect(code int, urlFn func(*flow.State, *server.Request) string) flow.StepFn

Redirect returns a StepFn that responds with an HTTP redirect. urlFn receives the current state and request to build the target URL dynamically.

flow.NewStep("redirect",
    output.Redirect(http.StatusFound, func(s *flow.State, req *server.Request) string {
        return "/orders/" + req.PathParam("id")
    }))

func Text

func Text(statusCode int, stateKey string) flow.StepFn

Text returns a StepFn that responds with the string value at stateKey.

Types

type Payload

type Payload struct {
	// contains filtered or unexported fields
}

Payload is a fluent builder for restapi.Request objects. It reads from the current flow State and server.Request to assemble the outbound call.

func REST

func REST(method, path string) *Payload

REST creates a new Payload builder for the given HTTP method and path. The path may contain {placeholder} segments resolved via PathParam.

output.REST("POST", "/orders")
output.REST("GET",  "/customers/{customer_id}/credit")

func (*Payload) Body

func (p *Payload) Body(value any) *Payload

Body sets a static request body.

func (*Payload) BodyFrom

func (p *Payload) BodyFrom(fn func(*flow.State, *server.Request) any) *Payload

BodyFrom derives the request body at call time from state and request.

output.REST("POST", "/orders").
    BodyFrom(func(s *flow.State, req *server.Request) any {
        var customer Customer
        s.Bind("load-customer", &customer)
        return map[string]any{"cnpj": customer.TaxID, "amount": req.QueryParam("amount")}
    })

func (*Payload) BodyFromState

func (p *Payload) BodyFromState(stateKey string) *Payload

BodyFromState sets the request body to the value stored at stateKey.

output.REST("POST", "/orders").BodyFromState("payload")

func (*Payload) Build

func (p *Payload) Build(req *server.Request, state *flow.State) (restapi.Request, error)

Build constructs the restapi.Request using the current state and request.

func (*Payload) Header

func (p *Payload) Header(key, value string) *Payload

Header adds a static header to the outbound request.

func (*Payload) HeaderFrom

func (p *Payload) HeaderFrom(key string, fn func(*flow.State, *server.Request) string) *Payload

HeaderFrom computes a header value from state and request.

func (*Payload) HeaderFromRequest

func (p *Payload) HeaderFromRequest(headerName string) *Payload

HeaderFromRequest copies a header from the inbound request to the outbound one.

.HeaderFromRequest("X-Trace-Id")   // forwards X-Trace-Id as-is

func (*Payload) HeaderFromRequestAs

func (p *Payload) HeaderFromRequestAs(destKey, srcHeader string) *Payload

HeaderFromRequestAs copies a header from the inbound request under a new name.

.HeaderFromRequestAs("X-Correlation-Id", "X-Trace-Id")

func (*Payload) PathParamFromRequest

func (p *Payload) PathParamFromRequest(placeholder, requestParam string) *Payload

PathParamFromRequest resolves a {placeholder} in the path from a URL path param.

output.REST("GET", "/customers/{id}").
    PathParamFromRequest("id", "customer_id")

func (*Payload) PathParamFromState

func (p *Payload) PathParamFromState(placeholder, stateKey, field string) *Payload

PathParamFromState resolves a {placeholder} in the path using a field from the value stored at stateKey.

output.REST("GET", "/customers/{tax_id}/credit").
    PathParamFromState("tax_id", "load-customer", "tax_id")

func (*Payload) Query

func (p *Payload) Query(key, value string) *Payload

Query adds a static query string parameter.

func (*Payload) QueryFrom

func (p *Payload) QueryFrom(key string, fn func(*flow.State, *server.Request) string) *Payload

QueryFrom computes a query parameter from state and request.