Skip to content

A continuation of HomeBox the inventory and organization system built for the Home User

14.7 KB
Raw Blame
package otel

import (
	"bytes"
	"context"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"math"
	"net/http"
	"strings"
	"time"

	"github.com/rs/zerolog/log"
	collogspb "go.opentelemetry.io/proto/otlp/collector/trace/v1"
	commonpb "go.opentelemetry.io/proto/otlp/common/v1"
	resourcepb "go.opentelemetry.io/proto/otlp/resource/v1"
	tracepb "go.opentelemetry.io/proto/otlp/trace/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/protobuf/proto"
)

// FrontendSpan represents a span sent from the frontend.
type FrontendSpan struct {
	TraceID      string                 `json:"traceId"`
	SpanID       string                 `json:"spanId"`
	ParentSpanID string                 `json:"parentSpanId,omitempty"`
	Name         string                 `json:"name"`
	Kind         string                 `json:"kind,omitempty"`
	StartTime    int64                  `json:"startTime"` // Unix milliseconds
	EndTime      int64                  `json:"endTime"`   // Unix milliseconds
	Attributes   map[string]interface{} `json:"attributes,omitempty"`
	Status       *SpanStatus            `json:"status,omitempty"`
	Events       []SpanEvent            `json:"events,omitempty"`
}

// SpanStatus represents the status of a span.
type SpanStatus struct {
	Code    string `json:"code"` // "ok", "error", "unset"
	Message string `json:"message,omitempty"`
}

// SpanEvent represents an event within a span.
type SpanEvent struct {
	Name       string                 `json:"name"`
	Time       int64                  `json:"time"` // Unix milliseconds
	Attributes map[string]interface{} `json:"attributes,omitempty"`
}

// TelemetryPayload represents the payload sent from the frontend.
type TelemetryPayload struct {
	ResourceAttributes map[string]interface{} `json:"resourceAttributes,omitempty"`
	Spans              []FrontendSpan         `json:"spans"`
}

// MaxTelemetryPayloadSize is the maximum size of telemetry payloads accepted by the proxy.
// This prevents denial-of-service attacks through excessively large payloads.
const MaxTelemetryPayloadSize = 1024 * 1024 // 1MB

const (
	traceIDLengthBytes = 16
	spanIDLengthBytes  = 8
	nanosPerMilli      = int64(1_000_000)
)

// telemetryValidationError marks malformed telemetry that should return HTTP 400.
type telemetryValidationError struct {
	msg string
}

func (e *telemetryValidationError) Error() string {
	return e.msg
}

// ProxyHandler handles telemetry data from the frontend.
// This forwards frontend telemetry data to the configured OTLP endpoint,
// allowing for distributed tracing across the full stack.
func (p *Provider) ProxyHandler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if p == nil || !p.IsEnabled() || p.cfg == nil || !p.cfg.ProxyEnabled {
			http.Error(w, "Telemetry proxy is disabled", http.StatusServiceUnavailable)
			return
		}

		// Only accept POST requests
		if r.Method != http.MethodPost {
			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
			return
		}

		// Enforce a hard request body limit and parse the payload.
		r.Body = http.MaxBytesReader(w, r.Body, MaxTelemetryPayloadSize)

		// Keep explicit body close for readability and symmetric cleanup.
		defer func(Body io.ReadCloser) {
			err := Body.Close()
			if err != nil {
				log.Error().Err(err).Msg("failed to close telemetry payload body")
			}
		}(r.Body)

		body, err := io.ReadAll(r.Body)
		if err != nil {
			if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
				http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
				return
			}
			log.Error().Err(err).Msg("failed to read telemetry payload")
			http.Error(w, "Failed to read request body", http.StatusBadRequest)
			return
		}

		var payload TelemetryPayload
		if err := json.Unmarshal(body, &payload); err != nil {
			log.Error().Err(err).Msg("failed to parse telemetry payload")
			http.Error(w, "Invalid JSON payload", http.StatusBadRequest)
			return
		}

		// Forward the spans to the OTLP endpoint
		if err := p.forwardToOTLP(r.Context(), payload); err != nil {
			if validationErr, ok := errors.AsType[*telemetryValidationError](err); ok {
				http.Error(w, "Invalid telemetry payload: "+validationErr.Error(), http.StatusBadRequest)
				return
			}

			log.Error().Err(err).Msg("failed to forward telemetry to OTLP endpoint")
			http.Error(w, "Failed to forward telemetry", http.StatusInternalServerError)
			return
		}

		// Return success
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusAccepted)
		_ = json.NewEncoder(w).Encode(map[string]interface{}{
			"processed": len(payload.Spans),
			"total":     len(payload.Spans),
		})
	}
}

// forwardToOTLP converts frontend spans to OTLP format and forwards them to the configured endpoint.
func (p *Provider) forwardToOTLP(ctx context.Context, payload TelemetryPayload) error {
	// Create an OTLP client based on configuration
	client, err := p.createProxyClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create OTLP client: %w", err)
	}
	defer func() {
		if shutdownErr := client.Shutdown(ctx); shutdownErr != nil {
			log.Warn().Err(shutdownErr).Msg("failed to shutdown OTLP client")
		}
	}()

	// Convert frontend spans to OTLP protobuf spans
	otlpSpans, err := p.convertToOTLPSpans(payload)
	if err != nil {
		return fmt.Errorf("failed to convert spans to OTLP format: %w", err)
	}

	// Upload the spans to the OTLP endpoint
	if err := client.UploadTraces(ctx, otlpSpans); err != nil {
		return fmt.Errorf("failed to upload traces: %w", err)
	}

	return nil
}

// otlpClient provides a unified interface for OTLP trace uploading
type otlpClient interface {
	UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) error
	Shutdown(ctx context.Context) error
}

// grpcClient wraps the gRPC OTLP client
type grpcClient struct {
	client collogspb.TraceServiceClient
	conn   *grpc.ClientConn
}

func (c *grpcClient) UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) error {
	req := &collogspb.ExportTraceServiceRequest{
		ResourceSpans: protoSpans,
	}
	_, err := c.client.Export(ctx, req)
	return err
}

func (c *grpcClient) Shutdown(_ context.Context) error {
	if c.conn != nil {
		return c.conn.Close()
	}
	return nil
}

// httpClient wraps the HTTP OTLP client
type httpClient struct {
	client  *http.Client
	url     string
	headers map[string]string
}

func (c *httpClient) UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) error {
	req := &collogspb.ExportTraceServiceRequest{
		ResourceSpans: protoSpans,
	}

	// Marshal to protobuf
	data, err := proto.Marshal(req)
	if err != nil {
		return fmt.Errorf("failed to marshal protobuf: %w", err)
	}

	// Create HTTP request
	httpReq, err := http.NewRequestWithContext(ctx, "POST", c.url, bytes.NewReader(data))
	if err != nil {
		return fmt.Errorf("failed to create HTTP request: %w", err)
	}

	httpReq.Header.Set("Content-Type", "application/x-protobuf")
	for k, v := range c.headers {
		httpReq.Header.Set(k, v)
	}

	// Send request
	resp, err := c.client.Do(httpReq)
	if err != nil {
		return fmt.Errorf("failed to send HTTP request: %w", err)
	}
	defer func() {
		_ = resp.Body.Close()
	}()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("HTTP request failed with status %d: %s", resp.StatusCode, string(body))
	}

	return nil
}

func (c *httpClient) Shutdown(_ context.Context) error {
	// HTTP client doesn't need explicit shutdown
	return nil
}

// createProxyClient creates an OTLP client for forwarding frontend spans.
func (p *Provider) createProxyClient(_ context.Context) (otlpClient, error) {
	headers := parseHeaders(p.cfg.Headers)

	switch strings.ToLower(p.cfg.Protocol) {
	case "http":
		scheme := "https"
		if p.cfg.Insecure {
			scheme = "http"
		}

		urlPath := "/v1/traces"
		if trimmedPrefix := strings.Trim(p.cfg.PathPrefix, " /"); trimmedPrefix != "" {
			urlPath = "/" + trimmedPrefix + urlPath
		}

		url := fmt.Sprintf("%s://%s%s", scheme, p.cfg.Endpoint, urlPath)

		return &httpClient{
			client:  &http.Client{Timeout: 30 * time.Second},
			url:     url,
			headers: headers,
		}, nil

	case "grpc", "":
		dialOpts := []grpc.DialOption{}
		if p.cfg.Insecure {
			dialOpts = append(dialOpts, grpc.WithTransportCredentials(insecure.NewCredentials()))
		} else {
			dialOpts = append(dialOpts, grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")))
		}

		conn, err := grpc.NewClient(p.cfg.Endpoint, dialOpts...)
		if err != nil {
			return nil, fmt.Errorf("failed to create gRPC client: %w", err)
		}

		client := collogspb.NewTraceServiceClient(conn)
		return &grpcClient{
			client: client,
			conn:   conn,
		}, nil

	default:
		return nil, fmt.Errorf("unsupported OTLP protocol: %s", p.cfg.Protocol)
	}
}

// convertToOTLPSpans converts frontend spans to OTLP protobuf format
func (p *Provider) convertToOTLPSpans(payload TelemetryPayload) ([]*tracepb.ResourceSpans, error) {
	if len(payload.Spans) == 0 {
		return nil, &telemetryValidationError{msg: "payload contains no spans"}
	}

	// Group spans by resource (in our case, all frontend spans share the same resource)
	serviceName := p.cfg.ServiceName + "-frontend"

	resourceAttrs := make([]*commonpb.KeyValue, 0)
	resourceAttrs = append(resourceAttrs, &commonpb.KeyValue{
		Key:   "service.name",
		Value: &commonpb.AnyValue{Value: &commonpb.AnyValue_StringValue{StringValue: serviceName}},
	})

	for k, v := range payload.ResourceAttributes {
		resourceAttrs = append(resourceAttrs, convertAttributeToProto(k, v))
	}

	// Convert all spans
	otlpSpans := make([]*tracepb.Span, 0, len(payload.Spans))
	for i, frontendSpan := range payload.Spans {
		otlpSpan, err := convertSpanToProto(frontendSpan)
		if err != nil {
			return nil, &telemetryValidationError{msg: fmt.Sprintf("span[%d] (%q): %v", i, frontendSpan.Name, err)}
		}
		otlpSpans = append(otlpSpans, otlpSpan)
	}

	// Create the resource spans structure
	resourceSpans := []*tracepb.ResourceSpans{
		{
			Resource: &resourcepb.Resource{
				Attributes: resourceAttrs,
			},
			ScopeSpans: []*tracepb.ScopeSpans{
				{
					Scope: &commonpb.InstrumentationScope{
						Name:    serviceName,
						Version: p.cfg.ServiceVersion,
					},
					Spans: otlpSpans,
				},
			},
		},
	}

	return resourceSpans, nil
}

// convertSpanToProto converts a single frontend span to OTLP protobuf format
func convertSpanToProto(frontendSpan FrontendSpan) (*tracepb.Span, error) {
	traceID, err := decodeHexID(frontendSpan.TraceID, traceIDLengthBytes, "trace ID")
	if err != nil {
		return nil, err
	}

	spanID, err := decodeHexID(frontendSpan.SpanID, spanIDLengthBytes, "span ID")
	if err != nil {
		return nil, err
	}

	// Parse parent span ID if present
	var parentSpanID []byte
	if frontendSpan.ParentSpanID != "" {
		parentSpanID, err = decodeHexID(frontendSpan.ParentSpanID, spanIDLengthBytes, "parent span ID")
		if err != nil {
			return nil, err
		}
	}

	if frontendSpan.StartTime < 0 || frontendSpan.EndTime < 0 {
		return nil, fmt.Errorf("invalid timestamps: start and end time must be non-negative")
	}
	if frontendSpan.EndTime < frontendSpan.StartTime {
		return nil, fmt.Errorf("invalid timestamps: end time must be greater than or equal to start time")
	}

	startTimeUnixNano, err := millisToNanos(frontendSpan.StartTime, "startTime")
	if err != nil {
		return nil, err
	}
	endTimeUnixNano, err := millisToNanos(frontendSpan.EndTime, "endTime")
	if err != nil {
		return nil, err
	}

	// Convert span kind
	spanKind := tracepb.Span_SPAN_KIND_INTERNAL
	switch strings.ToLower(frontendSpan.Kind) {
	case "client":
		spanKind = tracepb.Span_SPAN_KIND_CLIENT
	case "server":
		spanKind = tracepb.Span_SPAN_KIND_SERVER
	case "producer":
		spanKind = tracepb.Span_SPAN_KIND_PRODUCER
	case "consumer":
		spanKind = tracepb.Span_SPAN_KIND_CONSUMER
	}

	// Convert attributes
	attrs := make([]*commonpb.KeyValue, 0, len(frontendSpan.Attributes))
	for k, v := range frontendSpan.Attributes {
		attrs = append(attrs, convertAttributeToProto(k, v))
	}

	// Convert events
	events := make([]*tracepb.Span_Event, 0, len(frontendSpan.Events))
	for _, event := range frontendSpan.Events {
		eventTimeUnixNano, err := millisToNanos(event.Time, "event.time")
		if err != nil {
			return nil, err
		}

		eventAttrs := make([]*commonpb.KeyValue, 0, len(event.Attributes))
		for k, v := range event.Attributes {
			eventAttrs = append(eventAttrs, convertAttributeToProto(k, v))
		}
		events = append(events, &tracepb.Span_Event{
			TimeUnixNano: eventTimeUnixNano,
			Name:         event.Name,
			Attributes:   eventAttrs,
		})
	}

	// Convert status
	status := &tracepb.Status{
		Code: tracepb.Status_STATUS_CODE_UNSET,
	}
	if frontendSpan.Status != nil {
		switch strings.ToLower(frontendSpan.Status.Code) {
		case "ok":
			status.Code = tracepb.Status_STATUS_CODE_OK
			status.Message = frontendSpan.Status.Message
		case "error":
			status.Code = tracepb.Status_STATUS_CODE_ERROR
			status.Message = frontendSpan.Status.Message
		}
	}

	return &tracepb.Span{
		TraceId:           traceID,
		SpanId:            spanID,
		ParentSpanId:      parentSpanID,
		Name:              frontendSpan.Name,
		Kind:              spanKind,
		StartTimeUnixNano: startTimeUnixNano,
		EndTimeUnixNano:   endTimeUnixNano,
		Attributes:        attrs,
		Events:            events,
		Status:            status,
	}, nil
}

func decodeHexID(raw string, expectedLen int, label string) ([]byte, error) {
	decoded, err := hex.DecodeString(raw)
	if err != nil {
		return nil, fmt.Errorf("invalid %s: %w", label, err)
	}
	if len(decoded) != expectedLen {
		return nil, fmt.Errorf("invalid %s length: got %d bytes, want %d", label, len(decoded), expectedLen)
	}
	return decoded, nil
}

func millisToNanos(ms int64, field string) (uint64, error) {
	if ms < 0 {
		return 0, fmt.Errorf("invalid %s: must be non-negative", field)
	}
	if ms > math.MaxInt64/nanosPerMilli {
		return 0, fmt.Errorf("invalid %s: value overflows nanosecond conversion", field)
	}
	return uint64(ms * nanosPerMilli), nil
}

// convertAttributeToProto converts an attribute to OTLP protobuf format
func convertAttributeToProto(key string, value interface{}) *commonpb.KeyValue {
	var anyValue *commonpb.AnyValue

	switch v := value.(type) {
	case string:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_StringValue{StringValue: v}}
	case int:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_IntValue{IntValue: int64(v)}}
	case int64:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_IntValue{IntValue: v}}
	case float64:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_DoubleValue{DoubleValue: v}}
	case bool:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_BoolValue{BoolValue: v}}
	default:
		anyValue = &commonpb.AnyValue{Value: &commonpb.AnyValue_StringValue{StringValue: fmt.Sprintf("%v", v)}}
	}

	return &commonpb.KeyValue{
		Key:   key,
		Value: anyValue,
	}
}