Builder Design Pattern

public final class HttpRequest {
    private final String url, method;
    private final Map<String, String> headers;
    private final Duration timeout;
    private final int retries;

    // Only the builder can call this, so a half-built request cannot exist.
    private HttpRequest(Builder b) {
        this.url = b.url;
        this.method = b.method;
        this.headers = Map.copyOf(b.headers);   // defensive copy: truly immutable
        this.timeout = b.timeout;
        this.retries = b.retries;
    }

    public static Builder post(String url) { return new Builder(url, "POST"); }

    public static final class Builder {
        private final String url, method;
        private final Map<String, String> headers = new LinkedHashMap<>();
        private Duration timeout = Duration.ofSeconds(10);   // sensible defaults
        private int retries = 0;

        private Builder(String url, String method) { this.url = url; this.method = method; }

        public Builder header(String k, String v) { headers.put(k, v); return this; }
        public Builder timeout(Duration d) { this.timeout = d; return this; }
        public Builder retries(int n) { this.retries = n; return this; }

        public HttpRequest build() {
            // One place to enforce cross-field rules the constructor couldn't.
            if (retries > 0 && !"GET".equals(method) && !headers.containsKey("Idempotency-Key"))
                throw new IllegalStateException("retrying a non-GET needs an idempotency key");
            return new HttpRequest(this);
        }
    }
}

// HttpRequest.post("/v1/orders").header("Content-Type", "application/json")
//            .timeout(Duration.ofSeconds(30)).build();

from dataclasses import dataclass, field, replace
from datetime import timedelta


# Python usually doesn't need a builder class: keyword arguments already name
# every parameter at the call site, and defaults kill the telescoping overloads.
#
#     HttpRequest(url="/v1/orders", method="POST", timeout=timedelta(seconds=30))
#
# Reach for a builder when steps must ACCUMULATE (repeated .header() calls) or
# when there are cross-field rules to validate once at the end.


@dataclass(frozen=True)
class HttpRequest:
    url: str
    method: str = "GET"
    headers: tuple[tuple[str, str], ...] = ()
    timeout: timedelta = timedelta(seconds=10)
    retries: int = 0


class HttpRequestBuilder:
    def __init__(self, url: str, method: str = "GET") -> None:
        self._req = HttpRequest(url=url, method=method)

    def header(self, k: str, v: str) -> "HttpRequestBuilder":
        self._req = replace(self._req, headers=self._req.headers + ((k, v),))
        return self

    def timeout(self, seconds: int) -> "HttpRequestBuilder":
        self._req = replace(self._req, timeout=timedelta(seconds=seconds))
        return self

    def build(self) -> HttpRequest:
        if self._req.retries and self._req.method != "GET":
            if not any(k == "Idempotency-Key" for k, _ in self._req.headers):
                raise ValueError("retrying a non-GET needs an idempotency key")
        return self._req

class HttpRequest {
public:
    class Builder;

    // Accessors only — every field is const, set once at construction.
    const std::string& url() const { return url_; }

private:
    friend class Builder;
    HttpRequest(std::string url, std::string method,
                std::map<std::string, std::string> headers,
                std::chrono::seconds timeout, int retries)
        : url_(std::move(url)), method_(std::move(method)),
          headers_(std::move(headers)), timeout_(timeout), retries_(retries) {}

    const std::string url_, method_;
    const std::map<std::string, std::string> headers_;
    const std::chrono::seconds timeout_;
    const int retries_;
};

class HttpRequest::Builder {
public:
    explicit Builder(std::string url, std::string method = "GET")
        : url_(std::move(url)), method_(std::move(method)) {}

    // Returning a reference (not a copy) keeps the chain allocation-free.
    Builder& header(std::string k, std::string v) {
        headers_.emplace(std::move(k), std::move(v));
        return *this;
    }
    Builder& timeout(std::chrono::seconds s) { timeout_ = s; return *this; }
    Builder& retries(int n) { retries_ = n; return *this; }

    HttpRequest build() && {   // && : build() consumes the builder, so it can
        return HttpRequest(std::move(url_), std::move(method_),   // move, not copy
                           std::move(headers_), timeout_, retries_);
    }

private:
    std::string url_, method_;
    std::map<std::string, std::string> headers_;
    std::chrono::seconds timeout_{10};
    int retries_ = 0;
};

public sealed class HttpRequest
{
    public string Url { get; }
    public string Method { get; }
    public IReadOnlyDictionary<string, string> Headers { get; }
    public TimeSpan Timeout { get; }
    public int Retries { get; }

    private HttpRequest(Builder b)
    {
        Url = b.UrlValue; Method = b.MethodValue;
        Headers = new Dictionary<string, string>(b.HeaderValues);
        Timeout = b.TimeoutValue; Retries = b.RetryValue;
    }

    public static Builder Post(string url) => new(url, "POST");

    public sealed class Builder
    {
        internal string UrlValue { get; }
        internal string MethodValue { get; }
        internal Dictionary<string, string> HeaderValues { get; } = new();
        internal TimeSpan TimeoutValue { get; private set; } = TimeSpan.FromSeconds(10);
        internal int RetryValue { get; private set; }

        internal Builder(string url, string method) => (UrlValue, MethodValue) = (url, method);

        public Builder Header(string k, string v) { HeaderValues[k] = v; return this; }
        public Builder Timeout(TimeSpan t) { TimeoutValue = t; return this; }
        public Builder Retries(int n) { RetryValue = n; return this; }

        public HttpRequest Build() => new(this);
    }
}

// C# often gets there with less: a record with `init` properties plus
// `with` expressions gives named, optional, immutable construction for free.
// Prefer the builder when you need accumulation or end-of-build validation.

class HttpRequestBuilder {
  #req = { method: 'GET', headers: {}, timeoutMs: 10_000, retries: 0 }

  constructor(url, method = 'GET') {
    this.#req.url = url
    this.#req.method = method
  }

  header(k, v) { this.#req.headers[k] = v; return this }
  timeout(ms)  { this.#req.timeoutMs = ms;  return this }
  retries(n)   { this.#req.retries = n;     return this }

  build() {
    const r = this.#req
    if (r.retries > 0 && r.method !== 'GET' && !r.headers['Idempotency-Key']) {
      throw new Error('retrying a non-GET needs an idempotency key')
    }
    // Freeze so the finished request can't be edited after validation.
    return Object.freeze({ ...r, headers: Object.freeze({ ...r.headers }) })
  }
}

export const post = url => new HttpRequestBuilder(url, 'POST')

// The plain-object alternative is extremely common in JS and perfectly good:
//   request({ url, method: 'POST', timeoutMs: 30_000 })
// The builder earns its place when steps accumulate or validation must run once.

package httpx

import "time"

type Request struct {
	url, method string
	headers     map[string]string
	timeout     time.Duration
	retries     int
}

// Go's idiomatic answer is functional options rather than a builder type: same
// named, optional, order-free construction, but the product is built in one
// call so there is no half-built builder to pass around by mistake.

type Option func(*Request)

func Header(k, v string) Option {
	return func(r *Request) { r.headers[k] = v }
}
func Timeout(d time.Duration) Option { return func(r *Request) { r.timeout = d } }
func Retries(n int) Option           { return func(r *Request) { r.retries = n } }

func NewRequest(url, method string, opts ...Option) (*Request, error) {
	r := &Request{url: url, method: method, headers: map[string]string{}, timeout: 10 * time.Second}
	for _, opt := range opts {
		opt(r)
	}
	if r.retries > 0 && r.method != "GET" && r.headers["Idempotency-Key"] == "" {
		return nil, errors.New("retrying a non-GET needs an idempotency key")
	}
	return r, nil
}

// req, err := httpx.NewRequest("/v1/orders", "POST",
//     httpx.Header("Content-Type", "application/json"),
//     httpx.Timeout(30*time.Second))

interface HttpRequest {
  readonly url: string
  readonly method: string
  readonly headers: Readonly<Record<string, string>>
  readonly timeoutMs: number
  readonly retries: number
}

class HttpRequestBuilder {
  private req: Omit<HttpRequest, 'headers'> & { headers: Record<string, string> }

  constructor(url: string, method = 'GET') {
    this.req = { url, method, headers: {}, timeoutMs: 10_000, retries: 0 }
  }

  // Returning `this` types the chain, so autocomplete works at every step.
  header(k: string, v: string): this { this.req.headers[k] = v; return this }
  timeout(ms: number): this          { this.req.timeoutMs = ms;  return this }
  retries(n: number): this           { this.req.retries = n;     return this }

  build(): HttpRequest {
    if (this.req.retries > 0 && this.req.method !== 'GET' && !this.req.headers['Idempotency-Key']) {
      throw new Error('retrying a non-GET needs an idempotency key')
    }
    return Object.freeze({ ...this.req, headers: Object.freeze({ ...this.req.headers }) })
  }
}

// TypeScript can go further than most languages here: a "staged builder" that
// returns a different interface from each step can make build() unavailable
// until the required fields are set — turning a runtime throw into a type error.