Proxy

The three participants

Every proxy setup has the same small cast. The client only ever sees the first one:

• Subject (interface) — the common contract, e.g. Image with a display() method. Client code depends only on this.
• RealSubject — the heavyweight or sensitive object doing the actual work, e.g. RealImage, which loads 5 MB from disk in its constructor.
• Proxy — implements the same Subject interface and holds a reference to the RealSubject (often null at first). Every call arrives here, and the proxy decides if and when to create or invoke the real object.

That decision — if and when — is the pattern's power. The proxy can delay creating the real object until the first call actually needs it (lazy). It can refuse the call outright (denied). It can answer from memory without forwarding at all (cached). Or it can serialize the call and send it to another machine (remote). Same shape, four superpowers.

The four classic kinds

• Virtual proxy — delays creating an expensive object until it's first needed. Our ImageProxy is one: no disk read until the first display().
• Protection proxy — checks who is calling before letting the call through. Guests can't reach deleteImage(); admins can.
• Remote proxy — a local stand-in for an object living on another machine; it hides the network plumbing (this is exactly what RPC/gRPC stubs are).
• Caching / smart proxy — memoizes results so repeat calls skip the real object, or adds housekeeping like reference counting and logging around each call.

interface Image {                       // Subject — the shared contract
  display(): void;
}

class RealImage implements Image {      // RealSubject — expensive!
  constructor(private filename: string) {
    console.log(`loading 5 MB ${filename} from disk…`);  // slow
  }
  display() { console.log(`showing ${this.filename}`); }
}

class ImageProxy implements Image {     // Proxy — same interface
  private real: RealImage | null = null;   // nothing loaded yet

  constructor(private filename: string) {} // cheap: just a string

  display() {
    if (!this.real) {                      // first call only:
      this.real = new RealImage(this.filename);  // load once (virtual)
    }
    this.real.display();                   // cached ever after
  }
}

const photo: Image = new ImageProxy("beach.png"); // instant — no disk
photo.display();   // loads 5 MB, then shows       (first call)
photo.display();   // shows instantly — from cache  (every later call)

You already use proxies every day

• ORM lazy relations — Hibernate hands you a proxy for order.getCustomer(); the actual database query fires only when you first touch a field.
• JavaScript's built-in `Proxy` — wraps any object and intercepts every property read/write, powering things like Vue's reactivity.
• API gateways — clients call one endpoint that authenticates, rate-limits, and logs before forwarding to real backend services.
• CDN edge caches — a CDN node is a caching proxy for the origin server: repeat requests are answered at the edge and never travel to the origin.

Reach for a Proxy when you need a gatekeeper

The pattern earns its keep whenever something should happen between the client and the real object — without either of them knowing:

• Lazy-init a heavy object — images, database connections, big reports. Pay the construction cost only when (and if) it's actually used.
• Access control — the real object shouldn't check roles itself; a protection proxy screens callers before the call ever arrives.
• Talk to a remote object — hide serialization and networking behind a local stand-in with the same interface (RPC stubs, service clients).
• Cache or log without touching the real class — memoize expensive answers, count references, or record every call, all from the wrapper. The real class stays clean (see [[single-responsibility]]).