goto

📝 The Readme reflects master HEAD code and applies to release 0.9.x. Since 0.9.x releases have significant differences than 0.8.x and earlier releases, please refer to the appropriate tag for older documentation.

📝 Jump to TOC if you'd rather skip the overview and just to specific features and APIs.

What is goto?

"I'm an agent of chaos" - The Joker

A multi-faceted "No-Code" chaos testing tool to help with automated testing, debugging, bug hunt, runtime analysis and investigations. Mostly when we've a task at hand to test a system, the system to be tested is either a client, a server, or some kind of a gateway/proxy that sits between a client and a server.

To test either of these 3 layers, you need at least one counterparty application:

• To test a client, we need a server to which the client can connect, send requests and get some response back. The server needs to be able to track the lifecycle of the client connections and various requests it received from the client so that the client functionality can be verified.
• To test a server, we need a client that can send some requests to the server and track the responses sent by the server. Again the client should be able to track the lifecycle of connections and requests/responses to be able to verify the server functionality.
• To test an intermediary proxy/gateway, we need both a test client as well as a test server, where the two could route some requests and responses through the intermediary and validate the correctness of the traffic flow.

Goto can play all the above roles to fill the missing piece of the puzzle, all based on configs so that you don't have to write any code.

It can act as:

• An A2A engine that can dynamically create "No Code" Agents and Clients. The agents can call other agents (over A2A) or MCP servers, or respond with a custom unary or streaming payload.
• An MCP engine that can dynamically create MCP servers and clients. The MCP servers can expose any number of tools, and a tool can expose one of the supported behaviors. Supported behaviors include serving response based on data fetched from a remote HTTP call, a remote MCP call, a remote A2A agent call, or respond with a custom unary or streaming payload.
• A client that can generate HTTP/S, TCP, and gRPC traffic to other services (including other goto instances), track summary results of the traffic, and report results via APIs as well as publish results to a Goto registry.
• A server that can act as an -- HTTP server with arbitrary REST APIs with custom responses. -- gRPC server that supports any arbitrary RPC service/methods based on a given set of proto files (or specs extracted from remote reflection) -- TCP server that offers a set of TCP behaviors to assist with TCP testing/debugging. -- UDP Server that can proxy UDP requests/responses to upstream endpoints. -- The server can track and report summary data about the received traffic. See the TOC for a complete list of server features.
• A proxy that can act as an HTTP/S, TCP, UDP, gRPC, or MCP passthrough proxy, allowing you to route traffic through a goto instance to an upstream server, and inspect the requests/responses.
• A tunnel that allows tunneling of HTTP/S and TCP traffic across multiple hops. This allows testing traffic behavior as it goes through overlay boundaries and through various intermediary proxies/gateways.
• A job executor that can run shell commands/scripts as well as make HTTP calls, collect and report results. It allows chaining of jobs together so that output of one job triggers another job with input. Additionally, jobs can be auto-executed via cron, and can act as a source of data for pipelines (more on this under pipelines)
• A registry to orchestrate operations across other goto instances, collect and summarize results from those goto instances, and make the federated summary results available via APIs. A goto registry can also be paired with another goto registry instance and export/load data from one to the other to keep another backup of the collected results.
• A K8s proxy that can connect to and read resource information from a K8s cluster and make it available via APIs. It also supports watching for resource changes, and act as a source of data for pipelines (see below)
• A complex multi-step pipeline orchestration engine that can:
  • Source data from Shell Commands/Scripts, Client-side HTTP calls, Server-side HTTP responses, K8s resources, K8s pod commands, and Tunneled traffic.
  • Feed the sourced data as input to transformation steps and/or to other source steps.
  • Run JSONPath, JQ, Go Template or Regex transformations on the sourced data to extract information that can be fed to other sources or sent as output.
  • Define stages to orchestrate invocation of sources and transformations in a specific sequence.
  • Define watches on sources so that any changes on the source (e.g. K8s resources, cron jobs, or HTTP traffic) triggers the pipeline that the source is attached to, allowing some complex steps of data extraction, transformation and analysis to occur each time some external event occurs.

How to use it?

Grab or Build

Docker images (Alpine Linux based)

core

• docker.io/uk0000/goto:0.9.5, docker.io/uk0000/goto:0.9.5-arm64
• Includes bash, curl, jq

net

• docker.io/uk0000/goto:0.9.5-net, docker.io/uk0000/goto:0.9.5-net-arm64
• Includes core pack
• Includes network utilities like ncat, nc, nmap, socat, tcpdump, dig, nslookup, iptables, ipvsadm, openssl

kube

• docker.io/uk0000/goto:0.9.5-kube, docker.io/uk0000/goto:0.9.5-kube-arm64
• Includes core and net packs
• Includes kubectl and etcdctl

perf

• docker.io/uk0000/goto:0.9.5-perf, docker.io/uk0000/goto:0.9.5-perf-arm64
• Includes core and net packs
• Includes hey and iftop

gRPC

• docker.io/uk0000/goto:0.9.5-grpc, docker.io/uk0000/goto:0.9.5-grpc-arm64
• Includes core and net packs
• Includes grpcurl

Or, build it locally on your machine

go build -o goto .

Launch

Start goto as a server with multiple ports and protocols.

📝 First port is treated as bootstrap port and uses HTTP protocol

goto --ports 8080,8081/http,8443/https,6000/grpc,7000/tcp,8000/rpc --rpcPort=3000 --grpcPort=9000

Show me the money some use cases please!

Now that you have goto running, what can you do with it?
Before we look into detailed features and APIs exposed by the tool, let's look at how this tool can be used in a few scenarios to understand it better.

Basic Scenarios

Scenario: Use HTTP client to send requests and track results

Scenario: Use HTTP server to respond to any arbitrary client HTTP requests

Scenario: HTTPS traffic with certificate validation

Scenario: Count number of requests received at each server instance for certain headers

K8S Scenarios

Scenario: Run dynamic traffic from K8s pods at startup

Scenario: Deal with transient pods

Scenario: Capture results from pods that may terminate anytime

Resiliency Scenarios

Scenario: Test a client's behavior upon service failure

Scenario: Track client hang-ups on server via request/connection timeouts

Outside-the-Box Scenarios

Scenario: Create HTTP chaos that HTTP libraries won't let you

See Use Cases for more examples.

TOC

Startup Command

Self Reflection

• Version
• APIs

AI

• A2A Agent
• MCP Server and Client

Traffic (Client)

• Goto's HTTP/gRPC/TCP Client Features (To run Traffic)
• Client JSON Schemas
• Client APIs and Results Examples
• Client gRPC Examples

gRPC

• gRPC Server and Client

HTTP Server

• Server Features
• Goto Headers
• Goto Server Logs
• Log APIs
• Events
• Metrics
• Listeners
• Listener Label
• Request Headers Tracking
• Request Timeout
• URIs
• Probes
• Requests Filtering
• Response Delay
• Response Headers
• Response Payload
• Ad-hoc Payload
• Stream (Chunked) Payload
• Response Status
• Response Triggers
• Status API
• Delay API
• Echo API
• Catch All

TCP Server

• TCP Server

Tunnel

• Tunnel

Proxy

• Proxy Features

Scripts

• Scripts Features

Jobs

• Jobs Features

K8s

• K8s Features

Pipelines

• Pipeline Features

Goto Registry

• Registry Features

• Registry APIs

  
  

> Goto Startup Command

To run:

goto --ports 8080,8081/http,8443/https,6000/grpc,7000/tcp,8000/rpc --rpcPort=3000 --grpcPort=9000

See Startup Command doc.

Back to TOC

> Goto Version

APIs

METHOD	URI	Description
GET	/version	Get version info of this goto instance.

Back to TOC

> Goto APIs

This API returns a list of Goto's admin APIs, grouped by features (prefixes)

APIs

METHOD	URI	Description
GET	/apis	Get a list of all APIs offered by this version of Goto.

Back to TOC

> Catch All

Any request that doesn't match any of the defined management APIs, and also doesn't match any proxy targets, gets treated by a catch-all response that sends HTTP 200 response by default (unless an override response code is set)

Back to TOC