httpexec

README

archon-http-executor

Reference HTTP need executor for the Archon need protocol.

Turns a need payload into an upstream HTTP call with timeouts, permanent vs transient error classification, and webhook resume — the production failure modes people hit after the first demo.

Install (library)

go get github.com/diogoX451/archon-http-executor@v0.1.0

Library usage

req, err := httpexec.ParseRequest(need.Payload)
if err != nil {
    // permanent — ack and drop
}
resp, err := httpexec.Do(ctx, req)
if err != nil {
    // network/timeout — redeliver OR post FailurePayload then ack
}
// marshal resp → PostWebhook(correlationID, payload)

Run the reference binary

go run ./cmd/http-executor \
  -bus-driver nats \
  -bus-url nats://127.0.0.1:4222 \
  -subject 'archon.need.http.>' \
  -api http://127.0.0.1:8080

Flag / env	Meaning
-bus-driver / ARCHON_BUS_DRIVER	Messaging driver (default nats)
-bus-url / ARCHON_BUS_URL	Driver URL (legacy NATS_URL still accepted)
-subject	Need subject(s)
-api	Orchestrator base URL

Optional: DELIVERY_TOKEN for X-Archon-Delivery-Token on the webhook.

The binary depends on archon-bus + a driver package (nats is blank-imported). Swapping brokers does not change the HTTP need library.

Need payload (golden-compatible)

{
  "method": "GET",
  "url": "https://example.com/health",
  "headers": {"Accept": "application/json"},
  "timeout": 15
}

See need_v1.json.

Related

• archon-need-protocol
• archon-executor-runtime
• archon-nats-bus
• archon-oss

License

Apache-2.0

Documentation

Overview

Package httpexec is a reference HTTP need executor for the Archon need protocol.

It turns a need payload {method,url,headers,body,timeout} into an upstream HTTP call and classifies failures so the bus can redeliver transient errors while permanent poison is acked.

Part of the Archon open-source toolkit: https://github.com/diogoX451/archon-oss

Index

• func ExpandNeedSubjects(raw string) []string
• func FailurePayload(req Request, err error) []byte
• type Request
  • func ParseRequest(payload json.RawMessage) (Request, error)
• type Response
  • func Do(ctx context.Context, req Request) (Response, error)

Functions

func ExpandNeedSubjects

func ExpandNeedSubjects(raw string) []string

ExpandNeedSubjects ensures "archon.need.http.>" also covers "archon.need.http".

func FailurePayload

func FailurePayload(req Request, err error) []byte

FailurePayload builds a structured error for the orchestrator when upstream cannot be reached (after best-effort webhook of failure).

Types

type Request

type Request struct {
	Method  string            `json:"method"`
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers"`
	Body    json.RawMessage   `json:"body"`
	// Timeout is seconds; 0 → 30s.
	Timeout int `json:"timeout"`
}

Request is the need payload for type "http".

func ParseRequest

func ParseRequest(payload json.RawMessage) (Request, error)

ParseRequest unmarshals and validates a need payload.

type Response

type Response struct {
	StatusCode int               `json:"status_code"`
	Headers    map[string]string `json:"headers"`
	Body       json.RawMessage   `json:"body"`
}

Response is posted back via webhook as the need result payload.

func Do

func Do(ctx context.Context, req Request) (Response, error)

Do executes the upstream request. Network/timeout errors are transient; 4xx from upstream is returned as a successful Response (caller decides).