hostmock

Documentation

Overview

Package hostmock provides a friendly pretend host for waPC calls.

It’s designed primarily for SDK development and advanced tests where you want to validate exactly what a component is sending to the Tarmac host—without needing a real host running. No real hosts were harmed in the making of these tests.

Why use hostmock?

• Validate routing: ensure calls use the expected namespace, capability, and function.
• Inspect payloads: plug in a PayloadValidator to assert protobuf contents.
• Script responses: return custom bytes or simulate failures.

When should I use it?

Most users writing functions should prefer component-level mocks:

• github.com/tarmac-project/sdk/http/mock
• github.com/tarmac-project/sdk/kv/mock

They’re simpler and avoid coupling your tests to the wire format. Reach for hostmock when you need to assert the waPC payloads or validate capability routing.

Quick start

m, _ := hostmock.New(hostmock.Config{
  ExpectedNamespace:  "tarmac",
  ExpectedCapability: "httpclient",
  ExpectedFunction:   "call",
  PayloadValidator: func(p []byte) error {
    // Unmarshal and assert fields here
    return nil
  },
  Response: func() []byte { return []byte("ok") },
})

// Inject into a component under test
resp, err := m.HostCall("tarmac", "httpclient", "call", []byte("payload"))

Behavior

• If Fail is true and Error is set, HostCall returns that error.
• If Fail is true and Error is nil, HostCall returns ErrOperationFailed.
• Otherwise, HostCall enforces ExpectedNamespace/Capability/Function and runs PayloadValidator when provided. If everything is in order, Response (when set) provides the return bytes; otherwise it returns nil.

Tips

• Use table-driven tests for different routing and payload cases.
• Keep the validator small and focused—decode, assert, return.
• Prefer component mocks unless you truly need wire-level checks.

Index

• Variables
• type Config
• type Mock
  • func New(config Config) (*Mock, error)
  • func (m *Mock) HostCall(namespace, capability, function string, payload []byte) ([]byte, error)

Variables

var (
	// ErrUnexpectedNamespace is returned when the namespace is not as expected.
	ErrUnexpectedNamespace = errors.New("unexpected namespace")

	// ErrUnexpectedCapability is returned when the capability is not as expected.
	ErrUnexpectedCapability = errors.New("unexpected capability")

	// ErrUnexpectedFunction is returned when the function is not as expected.
	ErrUnexpectedFunction = errors.New("unexpected function")

	// ErrOperationFailed is returned when Fail is set without a custom error.
	ErrOperationFailed = errors.New("operation failed")
)

Types

type Config

type Config struct {
	// ExpectedNamespace defines the namespace expected in the host call.
	ExpectedNamespace string

	// ExpectedCapability defines the capability expected in the host call.
	ExpectedCapability string

	// ExpectedFunction defines the function name expected in the host call.
	ExpectedFunction string

	// Error is the error to return if the mock is configured to fail.
	Error error

	// PayloadValidator validates the payload passed to the host call.
	PayloadValidator func([]byte) error

	// Response defines the response to return for the host call.
	Response func() []byte

	// Fail indicates whether the mock should return an error.
	Fail bool
}

Config represents the configuration for creating a Mock instance.

type Mock

type Mock struct {
	// ExpectedNamespace defines the namespace expected in the host call.
	ExpectedNamespace string

	// ExpectedCapability defines the capability expected in the host call.
	ExpectedCapability string

	// ExpectedFunction defines the function name expected in the host call.
	ExpectedFunction string

	// Error is the error to return if the mock is configured to fail.
	Error error

	// PayloadValidator validates the payload passed to the host call.
	PayloadValidator func([]byte) error

	// Response defines the response to return for the host call.
	Response func() []byte

	// Fail indicates whether the mock should return an error.
	Fail bool
}

Mock simulates a host call interface with validation and configurable responses.

func New

func New(config Config) (*Mock, error)

New creates a new instance of the Mock based on the provided Config.

func (*Mock) HostCall

func (m *Mock) HostCall(namespace, capability, function string, payload []byte) ([]byte, error)

HostCall simulates a host call, validating inputs and returning a response or error.