transport

README

transport

Universal multi-protocol transport layer for nexss-kernel actions.

Universal multi-protocol transport layer for nexss-kernel actions.

                  ┌─────────────────────────────────┐
                  │      nexss-kernel actions       │
                  └────────────────┬────────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         │                         │                         │
         ▼                         ▼                         ▼
   thttp (REST/SSE)         tcli (CLI Tool)          tbus (Event Bus)
   tworker (Workers)        cron (Scheduler)         taskqueue (Task Queue)

Supported Protocols & Transports

• thttp: Standard HTTP/REST, Server-Sent Events (SSE), streaming NDJSON, and automatic tag-based binding (path, query, header, cookie, form).
• tcli: CLI commands, subcommands, flag parsing (cli:"flag,f"), positional arguments, and automated --help generation.
• tbus: Zero-allocation, in-process event bus binding with direct memory routing.
• tworker: Managed background worker schedules with auto-recovery and isolated request contexts.
• cron: Precise cron-scheduled jobs using standard cron syntax or duration intervals.
• taskqueue: In-process task queue with priority lanes (High, Normal, Low), retries, dead-letter queue (DLQ), and panic recovery.
• mediator: CQRS-style mediator supporting 1:1 typed commands and 1:N event publishing.

Installation

go get github.com/nexssp/transport@latest

Quick Start

1. HTTP Server

server := thttp.New(":8080")
server.Mount([]action.AnyAction{myAction})
server.Do(ctx, nil)

2. CLI Tool

cli := tcli.New()
cli.Mount([]action.AnyAction{myAction})
cli.Do(ctx, nil)

3. Background Workers

workerTransport := tworker.New()
workerTransport.Mount([]action.AnyAction{myAction})
workerTransport.Do(ctx, nil)

Documentation

Overview

Package transport defines the universal boundary interface for Nexss applications. Concrete adapters (thttp, tcli, tbus, cron, tworker) translate incoming network or CLI invocations into typed action.Executable dispatches.

Index

• Constants
• func MapToHTTPStatus(k xerr.Kind) int
• type Transport

Constants

const (
	HeaderRequestID   = "X-Request-ID"
	HeaderExecutionID = "X-Execution-ID"
	HeaderTraceID     = "X-Trace-ID"
	HeaderSpanID      = "X-Span-ID"
)

Standard transport-level correlation headers and keys.

Functions

func MapToHTTPStatus

func MapToHTTPStatus(k xerr.Kind) int

MapToHTTPStatus converts an xerr.Kind to its corresponding standard HTTP status code.

Types

type Transport

type Transport interface {
	fmt.Stringer

	// CanHandle reports whether this transport can process the given routing binding.
	CanHandle(b action.Binding) bool

	// Mount registers actions into the transport's internal routing table.
	Mount(actions []action.AnyAction)

	// Do starts the transport listener loop and blocks until ctx is canceled.
	Do(ctx context.Context, v any) (any, error)
}

Transport defines the universal lifecycle and routing contract for protocol listeners.