Extensions¶

package main

import (
    "context"
    "log"
    "net/http"

    "github.com/jhonsferg/relay"
    relaymetrics  "github.com/jhonsferg/relay/ext/metrics"
    relayprom     "github.com/jhonsferg/relay/ext/prometheus"
    relaytracing  "github.com/jhonsferg/relay/ext/tracing"
    relayzap      "github.com/jhonsferg/relay/ext/zap"

    "go.opentelemetry.io/otel"
    "go.uber.org/zap"
)

func main() {
    logger, err := zap.NewProduction()
    if err != nil {
        log.Fatalf("failed to build zap logger: %v", err)
    }
    defer logger.Sync()

    client, err := relay.New(
        relay.WithBaseURL("https://api.example.com"),
        relay.WithTimeout(30),
        relayzap.WithZap(logger),
        relaytracing.WithTracing(otel.GetTracerProvider(), otel.GetTextMapPropagator()),
        relaymetrics.WithOTelMetrics(otel.GetMeterProvider()),
        relayprom.WithPrometheus(
            relayprom.WithNamespace("myapp"),
        ),
    )
    if err != nil {
        log.Fatalf("failed to create relay client: %v", err)
    }

    ctx := context.Background()
    resp, err := client.Get(ctx, "/users/42")
    if err != nil {
        log.Fatalf("request failed: %v", err)
    }
    defer resp.Body.Close()

    log.Printf("status: %d", resp.StatusCode)
}

type Option func(*Client) error

// Conceptual example of how an extension wraps the transport.
// This is the pattern used internally by every relay extension.
package myext

import (
    "net/http"
    "github.com/jhonsferg/relay"
)

type loggingTransport struct {
    base http.RoundTripper
}

func (t *loggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // pre-request logic
    resp, err := t.base.RoundTrip(req)
    // post-request logic
    return resp, err
}

// WithLogging is an Option that wraps the existing transport.
func WithLogging() relay.Option {
    return func(c *relay.Client) error {
        c.Transport = &loggingTransport{base: c.Transport}
        return nil
    }
}

client, err := relay.New(
    relaytracing.WithTracing(tp, propagator),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close() // flushes tracing spans and other extension resources

package reqid

import (
    "crypto/rand"
    "encoding/hex"
    "net/http"

    "github.com/jhonsferg/relay"
)

type requestIDTransport struct {
    base   http.RoundTripper
    header string
}

func (t *requestIDTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // Clone the request so we do not mutate the caller's copy.
    r2 := req.Clone(req.Context())
    if r2.Header == nil {
        r2.Header = make(http.Header)
    }
    r2.Header.Set(t.header, newID())
    return t.base.RoundTrip(r2)
}

func newID() string {
    b := make([]byte, 8)
    _, _ = rand.Read(b)
    return hex.EncodeToString(b)
}

// WithRequestID injects a random request ID into every outgoing request
// using the specified header name. Pass an empty string to use the
// default "X-Request-ID".
func WithRequestID(header string) relay.Option {
    return func(c *relay.Client) error {
        if header == "" {
            header = "X-Request-ID"
        }
        c.Transport = &requestIDTransport{
            base:   c.Transport,
            header: header,
        }
        return nil
    }
}

client, err := relay.New(
    relay.WithBaseURL("https://api.example.com"),
    reqid.WithRequestID(""), // uses default "X-Request-ID"
)

package priority

import (
    "fmt"
    "github.com/jhonsferg/relay"
)

// WithPriority sets a priority tier header on a single request.
func WithPriority(level int) relay.RequestOption {
    return func(req *relay.Request) error {
        if level < 1 || level > 5 {
            return fmt.Errorf("priority must be between 1 and 5, got %d", level)
        }
        req.Header.Set("X-Priority", fmt.Sprintf("%d", level))
        return nil
    }
}

resp, err := client.Get(ctx, "/jobs/heavy",
    priority.WithPriority(3),
)