Proxy Design Pattern

public interface Customer {
    String name();
    CreditReport creditReport();
    void exportPii(Path destination);
}

public final class CustomerProxy implements Customer {

    private final CustomerId id;
    private final String cachedName;      // came free with the list query
    private final Permissions caller;
    private CustomerRecord real;          // created on first genuine need

    public CustomerProxy(CustomerId id, String cachedName, Permissions caller) {
        this.id = id;
        this.cachedName = cachedName;
        this.caller = caller;
    }

    @Override public String name() {
        return cachedName;                // the list never triggers a load
    }

    @Override public CreditReport creditReport() {
        return real().creditReport();
    }

    @Override public void exportPii(Path destination) {
        // A protection proxy refuses BEFORE the expensive object exists.
        if (!caller.has("pii:export")) {
            throw new AccessDenied("pii:export required");
        }
        real().exportPii(destination);
    }

    private synchronized CustomerRecord real() {
        // synchronized, not a plain null check: two threads hitting an unloaded
        // proxy is the classic way to pay the expensive cost twice.
        if (real == null) real = CustomerRecord.load(id);
        return real;
    }
}

// For a wide interface, don't hand-write the forwarding — generate it:
//
//     Customer guarded = (Customer) java.lang.reflect.Proxy.newProxyInstance(
//         Customer.class.getClassLoader(),
//         new Class<?>[]{ Customer.class },
//         (p, method, args) -> { check(method); return method.invoke(record, args); });
//
// This is exactly how Spring's @Transactional and Hibernate's lazy entities work:
// the bean you autowire is usually a generated proxy, not your class.

class CustomerProxy:
    """__getattr__ is only called for attributes that AREN'T found normally, which
    makes it the perfect hook for a virtual proxy: define the cheap things, and
    let everything else trigger the load."""

    def __init__(self, customer_id: str, cached_name: str, permissions: set[str]) -> None:
        self._id = customer_id
        self._name = cached_name
        self._permissions = permissions
        self._real: CustomerRecord | None = None

    @property
    def name(self) -> str:
        return self._name              # answered without loading anything

    def export_pii(self, destination: Path) -> None:
        if "pii:export" not in self._permissions:
            raise AccessDenied("pii:export required")
        self._load().export_pii(destination)

    def _load(self) -> CustomerRecord:
        if self._real is None:
            self._real = CustomerRecord.load(self._id)
        return self._real

    def __getattr__(self, item: str):
        # Anything not defined above — credit_report, addresses, … — loads first.
        return getattr(self._load(), item)


# Django ships this pattern where you'd least expect it: `request.user` is a
# SimpleLazyObject, so the session lookup and user query only happen if a view
# actually touches the user. Views that don't, don't pay.
#
# For the single-attribute case, functools.cached_property is the whole pattern
# in one decorator — compute once on first access, keep the value thereafter.

#include <memory>
#include <optional>

class Customer {
public:
    virtual ~Customer() = default;
    virtual std::string name() const = 0;
    virtual CreditReport creditReport() = 0;
};

class CustomerProxy final : public Customer {
public:
    CustomerProxy(CustomerId id, std::string cachedName)
        : id_(std::move(id)), name_(std::move(cachedName)) {}

    std::string name() const override { return name_; }

    CreditReport creditReport() override { return real().creditReport(); }

private:
    CustomerRecord& real() {
        // std::call_once, not `if (!ptr)`: this is the same double-checked
        // locking hazard the Singleton page walks through, and the standard
        // library already solved it.
        std::call_once(flag_, [this] { real_ = CustomerRecord::load(id_); });
        return *real_;
    }

    CustomerId id_;
    std::string name_;
    std::once_flag flag_;
    std::unique_ptr<CustomerRecord> real_;
};

// C++ is soaked in proxies, and two are worth knowing by name:
//
//   std::shared_ptr  — a smart reference: a proxy that counts references and
//                      destroys the subject when the last one goes away.
//   std::vector<bool>::reference — the notorious one. vector<bool> packs bits,
//                      so operator[] cannot return a real bool&; it returns a
//                      PROXY object that pretends to be one. That is why
//                      `auto b = v[0];` behaves unlike every other container.

public interface ICustomer
{
    string Name { get; }
    CreditReport CreditReport();
    void ExportPii(string destination);
}

public sealed class CustomerProxy(CustomerId id, string cachedName, IPermissions caller) : ICustomer
{
    // Lazy<T> is a virtual proxy with the thread safety already argued about
    // and settled — it is thread-safe by default.
    private readonly Lazy<CustomerRecord> _real = new(() => CustomerRecord.Load(id));

    public string Name => cachedName;                 // no load

    public CreditReport CreditReport() => _real.Value.CreditReport();

    public void ExportPii(string destination)
    {
        if (!caller.Has("pii:export"))
            throw new UnauthorizedAccessException("pii:export required");

        _real.Value.ExportPii(destination);
    }
}

// For a wide interface, DispatchProxy generates the forwarding at runtime:
//
//     public class AuditProxy<T> : DispatchProxy where T : class
//     {
//         public T? Target { get; set; }
//         protected override object? Invoke(MethodInfo? m, object?[]? args)
//         {
//             Log(m!.Name);
//             return m.Invoke(Target, args);
//         }
//     }
//
// EF Core's lazy-loading proxies are the same machinery: mark a navigation
// property `virtual`, and the entity you get back is a generated subclass that
// queries the database the first time you touch it.

// JavaScript is the one language where this pattern is a built-in language
// feature, named after itself. A Proxy intercepts operations on any object.

const customerProxy = (id, cachedName, permissions) => {
  let real = null
  const load = () => (real ??= CustomerRecord.load(id))

  return new Proxy(
    { name: cachedName },
    {
      get(stub, prop) {
        if (prop in stub) return stub[prop]          // answered without loading

        if (prop === 'exportPii' && !permissions.has('pii:export')) {
          return () => { throw new AccessDenied('pii:export required') }
        }

        const value = load()[prop]
        return typeof value === 'function' ? value.bind(real) : value
      },
    },
  )
}

// `.bind(real)` matters: pull a method off the subject and call it through the
// proxy and `this` would otherwise be the proxy, not the record.
//
// Vue 3's entire reactivity system is this — component state is wrapped in a
// Proxy whose `get` trap records which component read which property, so a later
// `set` knows exactly what to re-render.

package customers

// Go has no dynamic proxies: no reflection-based interception, no generated
// subclasses. You write the struct, and the compiler checks you implemented the
// whole interface — verbose, but there is no hidden magic to debug at 3am.

type Customer interface {
	Name() string
	CreditReport(ctx context.Context) (Report, error)
	ExportPII(ctx context.Context, dst string) error
}

type proxy struct {
	id    string
	name  string
	perms map[string]bool

	once sync.Once
	real *Record
	terr error
}

func (p *proxy) Name() string { return p.name }   // no load

func (p *proxy) load(ctx context.Context) (*Record, error) {
	p.once.Do(func() { p.real, p.terr = Load(ctx, p.id) })
	return p.real, p.terr
}

func (p *proxy) ExportPII(ctx context.Context, dst string) error {
	if !p.perms["pii:export"] {
		return ErrForbidden          // refused before anything is loaded
	}
	rec, err := p.load(ctx)
	if err != nil {
		return err
	}
	return rec.ExportPII(ctx, dst)
}

// The remote proxy is everywhere in Go and nobody calls it one: a generated
// gRPC client stub implements the same interface as the server handler, and
// turns each method call into a network round trip.

interface Customer {
  readonly name: string
  creditReport(): Promise<CreditReport>
  exportPii(destination: string): Promise<void>
}

class CustomerProxy implements Customer {
  #real: CustomerRecord | null = null

  constructor(
    private readonly id: CustomerId,
    readonly name: string,                 // cheap, came with the list query
    private readonly permissions: ReadonlySet<string>,
  ) {}

  async creditReport(): Promise<CreditReport> {
    return (await this.#load()).creditReport()
  }

  async exportPii(destination: string): Promise<void> {
    if (!this.permissions.has('pii:export')) {
      throw new AccessDenied('pii:export required')
    }
    await (await this.#load()).exportPii(destination)
  }

  async #load(): Promise<CustomerRecord> {
    // Cache the PROMISE, not the value: caching the value still lets two
    // concurrent callers start two loads before either finishes.
    this.#loading ??= CustomerRecord.load(this.id)
    return (this.#real ??= await this.#loading)
  }

  #loading: Promise<CustomerRecord> | null = null
}

// The native Proxy is typed as `ProxyHandler<T>`, but note the honest limit:
// TypeScript cannot verify that your `get` trap returns the right type per
// property, so a hand-written class like this one is the type-safe option.