remote

REMOTE 🏝

Crazy Simple, Chainable HTTP Client for Go

Remote is a paper-thin wrapper for Go's HTTP library, that gives you sensible defaults, a pretty API with some modern conveniences, and full control of your HTTP requests. It's the fastest and easiest way to make an HTTP call using Go.

Inspired by Brandon Romano's Wrecker. Thanks Brandon!

How to Get data from an HTTP server

// Structure to read remote data into
users := []struct {
    ID string
    Name string
    Username string
    Email string
}{}

// Get data from a remote server
remote.Get("https://jsonplaceholder.typicode.com/users").
    Result(users, nil).
    Send()

How to Post/Put/Patch/Delete data to an HTTP server

// Data to send to the remote server
user := map[string]string{
    "id": "ABC123",
    "name": "Sarah Connor",
    "email": "sarah@sky.net",
}

// Structure to read response into
response := map[string]string{}

// Post data to the remote server (use your own URL)
remote.Post("https://example.com/post-service").
    JSON(user). // encode the user object into the request body as JSON
    Result(response, nil). // parse response (or error) into a data structure
    Send()

Handling HTTP Errors

Web services represent errors in a number of ways. Some simply return an HTTP error code, while others return complex data structures in the response body. REMOTE works with each style of error handling, so that your app always has the best information to work from.

// Structure to read successful response into.  This format is specific to the HTTP service.
success := struct{Name: string, Value: string, Comment: string}

// Structure to read failed response data into.  This format is specific to the HTTP service.
failure := struct(Code: int, Reason: string, StackTrace: string)

transaction := remote.Get("https://example.com/service-that-might-error").
    .Result(&success, &failure)

// Transaction returns an error **IF** the HTTP response code is not successful (200-299)
if err := transaction.Send(); err != nil {
    // Handle errors here.
    // `failure` variable will be populated with data from the remote service
    return
}

// Fall through to here means that the transaction was successful.  
// `success` variable will be populated with data from the remote service.

Middleware

Middleware allows you to modify a request before it is sent to the remote server, or modify the response after it is returned by the remote server. Each middleware object includes three hooks

Included Middleware

// AUTHORIZATION adds a simple "Authorization" header to your request
remote.Get("https://jsonplaceholder.typicode.com/users").
    Use(middleware.Authorization(myAuthorizationKey)).
    Result(users, nil).
    Send()

// BASIC AUTH adds a Base64 encoded "Authorization" header to your request,
// which follows the basic authorization standard
remote.Get("https://jsonplaceholder.typicode.com/users").
    Use(middleware.BasicAuth(username, password)).
    Result(users, nil).
    Send()

// DEBUG prints debugging statements to the console
remote.Get("https://jsonplaceholder.typicode.com/users").
    Use(middleware.Debug()).
    Result(users, nil).
    Send()

// OPAQUE makes direct changes to the URL string.
remote.Get("https://jsonplaceholder.typicode.com/users").
    Use(middleware.Opaque(opaqueURLStringHere)).
    Result(users, nil).
    Send()

Writing Custom Middleware

It's easy to write additional, custom middleware for your project. Just follow the samples in the /middleware folder, and pass in any object that follows the Middleware interface.

Config(*Transaction) allows you to change the transaction configuration before it is compiled into an HTTP request. This is typically the simplest, and easiest way to modify a request

Request(*http.Request) allows you to modify the raw HTTP request before it is sent to the remote server. This is useful in the rare cases when you need to make changes to a request that this library doesn't support.

Response(*http.Response) allows you to modify the raw HTTP response before its results are parsed and returned to the caller.

Turbine Queue

Remote works with the Turbine queue to queue and retry transactions.

myQueue := queue.New(WithConsumers(remote.Consumer()))

remote.Post("https://server.com").
    Queue(myQueue).
    Send()

Publish Transactions to a Queue

When you create a remote Transaction, you can add it to a Turbine queue using the .Queue method. This method allows you to include a list of Task Options that modify the task that is published to the queue. For instance, you can choose a specific task priority, delay time, or maximum retry count.

remote.Post("https://server.com").
    Queue(
        myQueue, 
        queue.WithPriority(0), // these options modify the created queue.Task
        queue.WithRetryCount(8)). // these options modify the created queue.Task
    Send()

IMPORTANT: When you queue a transaction it is executed asynchronously, and possibly several times until successful. This means that you cannot receive live responses in your application anymore. So, Result and Error modifiers will be ignored, as will the AfterRequest portions of any options.

Consume Transactions from a Queue

This library includes a turbine queue.Consumer that executes remote.Transactions from the queue. This consumer can take any number of remote.Options to configure how queued transactions will be executed.

// Create a queue.Consumer to handle remote transactions
consumer := remote.Consumer(
    remote.WithClient(...) // these options modify the created remote.Transaction
)

myQueue := queue.New(WithConsumers(consumer))

Pull Requests Welcome

Original versions of this library have been used in production on commercial applications for years, and have helped speed up development for everyone involved.

I'm now open sourcing this library, and others, with hopes that you'll also benefit from an easy HTTP library.

Please use GitHub to make suggestions, pull requests, and enhancements. We're all in this together! 🏝