transport

README

entiqon/transport

transport is a minimal Go library that provides reusable primitives for executing requests across different communication transports.

The library focuses strictly on the communication layer, allowing applications to interact with external systems through a unified transport abstraction.

It is designed to remain small, composable, and transport-focused, leaving business logic, orchestration, and data transformation to the application layer.

---

Architecture

The library is organized into small composable packages:

transport (core primitives)
├── Client
├── Request
└── Response
      ↑
client/api (HTTP implementation)
      ↑
auth (authentication contracts)
      ↑
credential (request mutation strategies)
      ↑
provider (credential resolution)

This layering keeps transport execution independent of authentication mechanisms and credential resolution logic.

---

Example

package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/entiqon/transport"
    "github.com/entiqon/transport/client/api"
)

func main() {

    ctx := context.Background()

    client := api.New(
        api.WithHTTPClient(http.DefaultClient),
    )

    req := &transport.Request{
        Method: "GET",
        Path:   "https://example.com",
    }

    resp, err := client.Execute(ctx, req)
    if err != nil {
        panic(err)
    }

    fmt.Println(resp.Status)
}

---

Credential Strategies

Credential strategies modify outgoing requests before execution.

AccessToken

client := api.New(
    api.WithCredential(
        credential.AccessToken("X-Access-Token", "token"),
    ),
)

BearerToken

client := api.New(
    api.WithCredential(
        credential.BearerToken("token"),
    ),
)

APIKey

client := api.New(
    api.WithCredential(
        credential.APIKey("X-API-Key", "key", credential.APIKeyHeader),
    ),
)

Basic

client := api.New(
    api.WithCredential(
        credential.Basic("user", "password"),
    ),
)

JWT

client := api.New(
    api.WithCredential(
        credential.JWT("Authorization", jwtToken),
    ),
)

HMAC

client := api.New(
    api.WithCredential(
        credential.HMAC("api-key", "secret"),
    ),
)

---

Credential Providers

Credential providers resolve credentials dynamically from configuration.

Example using an OAuth2 provider:

client := api.New(
    api.WithAuthProvider(
        provider.OAuth2(http.DefaultClient),
        authConfig,
    ),
)

Providers may optionally support credential refresh when tokens expire.

---

License

Originally created by Isidro A. Lopez G.
Maintained by Entiqon Labs

MIT License

Documentation

Overview

Package transport provides minimal primitives for executing requests across different communication transports.

The library focuses strictly on the communication layer, allowing applications to interact with external systems through a unified transport abstraction.

transport intentionally avoids application concerns such as:

• business workflows
• orchestration logic
• domain transformations

These responsibilities belong to the consuming application.

Authentication is handled through pluggable credential strategies that modify outgoing transport requests before execution.

Credential strategies implement the `auth.Credential` interface and are applied through client configuration using `WithCredential`.

Credentials may also be resolved dynamically using authentication providers. Providers implement the `auth.Provider` interface and resolve credentials from configuration before a request is executed.

Some providers maintain internal credential state (such as OAuth2 access tokens) and may optionally implement the `auth.Refreshable` interface to allow forced credential renewal.

The project is designed to remain:

• small
• composable
• transport-focused

allowing it to be embedded easily into larger systems.

Index

• type Client
• type Request
• type Response
  • func (r *Response) Header(name string) string
  • func (r *Response) OK() bool
  • func (r *Response) StatusText() string

Types

type Client

type Client interface {

	// Execute performs the provided transport Request.
	//
	// The request is validated, transformed into the underlying
	// protocol representation, and executed using the configured
	// transport mechanism.
	//
	// If the request cannot be executed, an error is returned.
	Execute(ctx context.Context, req *Request) (*Response, error)
}

Client represents a transport capable of executing communication requests to external systems.

Implementations are responsible for translating a Request into a concrete protocol operation (such as an HTTP request), executing it, and returning the resulting Response.

type Request

type Request struct {

	// Connection identifies the logical connection or integration
	// context associated with the request. Higher-level components
	// may use this value to resolve endpoints or credentials.
	Connection string

	// Method defines the request method (e.g., GET, POST, PUT, DELETE).
	Method string

	// Path defines the target resource path or full endpoint URL.
	Path string

	// Headers contains optional HTTP headers applied to the request.
	Headers map[string]string

	// Query contains optional query parameters appended to the request URL.
	Query map[string]string

	// Body represents the request payload.
	//
	// The value must implement io.Reader and will be passed directly
	// to the underlying transport request.
	Body io.Reader
}

Request represents a transport request executed by a Client.

It describes the information required to perform an outbound communication request independently of a specific transport implementation. The client is responsible for translating this structure into the underlying protocol request (e.g., HTTP).

type Response

type Response struct {

	// Status is the HTTP status code returned by the server.
	Status int

	// Headers contains the normalized response headers returned by the server.
	//
	// Multi-value headers may be flattened depending on the transport
	// implementation.
	Headers map[string]string

	// Body contains the raw response payload returned by the server.
	Body []byte

	// Raw contains the original HTTP response returned by the underlying
	// transport implementation.
	//
	// The response body is consumed by the transport client when building
	// the Response structure, therefore Raw.Body should not be read.
	// The normalized Body field contains the full payload.
	Raw *http.Response
}

Response represents the result of executing a transport Request.

It contains normalized response information together with the raw protocol response returned by the underlying transport implementation.

func (*Response) Header

func (r *Response) Header(name string) string

Header returns the value of the specified response header.

If the header is not present, an empty string is returned.

func (*Response) OK

func (r *Response) OK() bool

OK reports whether the response status code indicates success according to HTTP semantics (status code in the 2xx range).

func (*Response) StatusText

func (r *Response) StatusText() string

StatusText returns the standard HTTP status text associated with the response status code.

It is equivalent to calling http.StatusText on the Status field and is provided as a convenience helper when logging or reporting transport responses.