# Proxy: The Stand-In at the Door

When every screen that can unlock the front door has to check for a guest itself, the one that forgets lets a guest in; a proxy is a stand-in that keeps the lock's own interface and controls the way in, so every caller gets the check without writing it. The same shape also delays slow work until it's needed and stands in for a service far away.

Journeyman · OOP · Updated November 17, 2026

By Gregor Dzierzon

## After this lesson you can

- Write a proxy: a stand-in that keeps an object's interface and controls the way in, such as checking who may call it
- Spot the smells that point to Proxy: the same check or setup code copied in front of every use of one object
- Tell a protection proxy, a virtual proxy and a remote proxy apart by what each one controls

## Key takeaways

- The smell: the same check, or the same setup work, copied in front of every use of one object, and one caller that forgot it.
- The cause: callers reach the real object directly, so each one has to guard the way in itself.
- The fix: a stand-in with the same interface that holds the real object and decides whether, and when, a call goes through.
- Protection proxies check who's asking, virtual proxies make the real object only when it's first needed, and remote proxies stand in for an object far away.

**Before this:** *Adapter*, which put the Bolt lock behind the hub's own `Lock` promise, and interfaces (a promise any class can keep).

Maya's sister is staying for the weekend, and the hub has a new kind of person: a **guest**. A guest can turn on a light or play music, but can't unlock the front door; only Maya (the owner) and Sam (family) can. Three things can unlock that door: the phone app, voice, and the wall panel. Each one was given the rule. This lesson is about what happened next, and about a stand-in that sits at the door, called a *proxy*.

## The symptom: three doors to one door

The front door here is the hub's `Lock`: the Bolt lock behind its adapter, written as one small class so the problem stands out. Each of the three controls checks for a guest before it unlocks:

```csharp
FrontDoor door = new FrontDoor();

PhoneAppUnlock("guest");
VoiceUnlock("guest");
WallPanelUnlock("guest");
WallPanelUnlock("Maya");

void PhoneAppUnlock(string person)
{
    Console.WriteLine($"Phone app, as {person}:");
    if (person == "guest") { Console.WriteLine("Front door: guests can't unlock it"); return; }
    door.Unlock();
}

void VoiceUnlock(string person)
{
    Console.WriteLine($"Voice, as {person}:");
    if (person == "guest") { Console.WriteLine("Front door: guests can't unlock it"); return; }
    door.Unlock();
}

void WallPanelUnlock(string person)
{
    Console.WriteLine($"Wall panel, as {person}:");
    door.Unlock();
}

interface ILock { void Lock(); void Unlock(); }

// The front door: the Bolt lock behind its adapter, as one small class.
class FrontDoor : ILock
{
    public void Lock() => Console.WriteLine("Front door: locked");
    public void Unlock() => Console.WriteLine("Front door: unlocked");
}
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: unlocked
Wall panel, as Maya:
Front door: unlocked
```

```java
interface Lock { void lock(); void unlock(); }

// The front door: the Bolt lock behind its adapter, as one small class.
class FrontDoor implements Lock {
    public void lock() { IO.println("Front door: locked"); }
    public void unlock() { IO.println("Front door: unlocked"); }
}

FrontDoor door = new FrontDoor();

void phoneAppUnlock(String person) {
    IO.println("Phone app, as " + person + ":");
    if (person.equals("guest")) { IO.println("Front door: guests can't unlock it"); return; }
    door.unlock();
}

void voiceUnlock(String person) {
    IO.println("Voice, as " + person + ":");
    if (person.equals("guest")) { IO.println("Front door: guests can't unlock it"); return; }
    door.unlock();
}

void wallPanelUnlock(String person) {
    IO.println("Wall panel, as " + person + ":");
    door.unlock();
}

void main() {
    phoneAppUnlock("guest");
    voiceUnlock("guest");
    wallPanelUnlock("guest");
    wallPanelUnlock("Maya");
}
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: unlocked
Wall panel, as Maya:
Front door: unlocked
```

```python
class FrontDoor:
    """The front door: the Bolt lock behind its adapter, as one small class."""

    def lock(self):
        print("Front door: locked")

    def unlock(self):
        print("Front door: unlocked")


door = FrontDoor()


def phone_app_unlock(person):
    print(f"Phone app, as {person}:")
    if person == "guest":
        print("Front door: guests can't unlock it")
        return
    door.unlock()


def voice_unlock(person):
    print(f"Voice, as {person}:")
    if person == "guest":
        print("Front door: guests can't unlock it")
        return
    door.unlock()


def wall_panel_unlock(person):
    print(f"Wall panel, as {person}:")
    door.unlock()


phone_app_unlock("guest")
voice_unlock("guest")
wall_panel_unlock("guest")
wall_panel_unlock("Maya")
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: unlocked
Wall panel, as Maya:
Front door: unlocked
```

```javascript
// The front door: the Bolt lock behind its adapter, as one small class.
class FrontDoor {
  lock() { console.log("Front door: locked"); }
  unlock() { console.log("Front door: unlocked"); }
}

const door = new FrontDoor();

function phoneAppUnlock(person) {
  console.log(`Phone app, as ${person}:`);
  if (person === "guest") { console.log("Front door: guests can't unlock it"); return; }
  door.unlock();
}

function voiceUnlock(person) {
  console.log(`Voice, as ${person}:`);
  if (person === "guest") { console.log("Front door: guests can't unlock it"); return; }
  door.unlock();
}

function wallPanelUnlock(person) {
  console.log(`Wall panel, as ${person}:`);
  door.unlock();
}

phoneAppUnlock("guest");
voiceUnlock("guest");
wallPanelUnlock("guest");
wallPanelUnlock("Maya");
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: unlocked
Wall panel, as Maya:
Front door: unlocked
```

```typescript
// A module of its own (export {}), so this Lock isn't mixed up with the browser's built-in Lock type.
export {};

interface Lock { lock(): void; unlock(): void; }

// The front door: the Bolt lock behind its adapter, as one small class.
class FrontDoor implements Lock {
  lock(): void { console.log("Front door: locked"); }
  unlock(): void { console.log("Front door: unlocked"); }
}

const door = new FrontDoor();

function phoneAppUnlock(person: string): void {
  console.log(`Phone app, as ${person}:`);
  if (person === "guest") { console.log("Front door: guests can't unlock it"); return; }
  door.unlock();
}

function voiceUnlock(person: string): void {
  console.log(`Voice, as ${person}:`);
  if (person === "guest") { console.log("Front door: guests can't unlock it"); return; }
  door.unlock();
}

function wallPanelUnlock(person: string): void {
  console.log(`Wall panel, as ${person}:`);
  door.unlock();
}

phoneAppUnlock("guest");
voiceUnlock("guest");
wallPanelUnlock("guest");
wallPanelUnlock("Maya");
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: unlocked
Wall panel, as Maya:
Front door: unlocked
```

Read the sixth line. The wall panel was written later, by someone who didn't know about guests, and it unlocks the front door for anyone standing in the kitchen. Nothing crashed; nothing even looks wrong in the wall panel's code.

- **The symptom:** the same check copied in front of every use of one object, and one caller that forgot it.
- **The cause:** every caller reaches the real lock directly, so every caller has to guard the way in itself. The rule "a guest can't unlock" has no home of its own.

## What would you try?

**Add the check to the wall panel.** Today's bug is fixed. The smartwatch app, next month, has the same chance to forget, and so does every caller after it.

**Put the check inside `FrontDoor`, or inside the Bolt adapter.** Now the lock has two jobs, locking and deciding who's allowed, and it needs to be told who's asking on every call. And the next lock, on the back door, needs its own copy of the rule.

**A facade, `hub.unlockFrontDoor(person)`, with the check inside.** That's a good front door for the screens. But any code holding the `Lock` itself can still call `unlock()` around it.

What we want is something that *is* a lock, as far as callers can tell, so nobody can tell it apart from the real one, but that checks who's asking before passing the call on.

## The fix: a stand-in at the door

A club's doors have a bouncer. You don't get a different, smaller club for being under age: you get the same door, with someone standing in it who checks your ID and lets you through, or doesn't. A photo app does something similar with a gallery: it shows a small thumbnail, and only loads the full picture when you tap it.

![Two everyday stand-ins: a bouncer at a club door checking a person's ID before letting them in, and a phone's grid of small photo thumbnails, where a tapped photo loads full size, labeled "loads when tapped"](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/f3ca79b0d41c4240a0b3eb9484676ba7.webp)

In code, the bouncer is a **proxy**: an object that keeps the same interface as the real one, holds the real one, and controls the way in. `GuardedLock` is a `Lock`; its `unlock()` checks the person first and passes the call on only for Maya and Sam. Every caller is handed a `GuardedLock`, made for the person using it:

![Proxy's roles: the wall panel asks unlock() of the stand-in at the door, which keeps the Lock promise, so the panel can't tell it from the real lock. The stand-in checks who's asking, then passes the call on to the real front door only if allowed; it is fenced as "who may come in"](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/2dfe3306f96d4dd4ad1081023fe236a4.webp)

```csharp
FrontDoor door = new FrontDoor();

PhoneAppUnlock("guest");
VoiceUnlock("guest");
WallPanelUnlock("guest");
WallPanelUnlock("Maya");

// Every caller gets a lock made for the person using it.
ILock LockFor(string person) => new GuardedLock(door, person);

void PhoneAppUnlock(string person) { Console.WriteLine($"Phone app, as {person}:"); LockFor(person).Unlock(); }
void VoiceUnlock(string person) { Console.WriteLine($"Voice, as {person}:"); LockFor(person).Unlock(); }
void WallPanelUnlock(string person) { Console.WriteLine($"Wall panel, as {person}:"); LockFor(person).Unlock(); }

interface ILock { void Lock(); void Unlock(); }

class FrontDoor : ILock
{
    public void Lock() => Console.WriteLine("Front door: locked");
    public void Unlock() => Console.WriteLine("Front door: unlocked");
}

// The stand-in at the door: the same promise, with the check in front of it.
class GuardedLock : ILock
{
    private readonly ILock real;
    private readonly string person;

    public GuardedLock(ILock real, string person)
    {
        this.real = real;
        this.person = person;
    }

    public void Lock() => real.Lock();

    public void Unlock()
    {
        if (person == "guest")
        {
            Console.WriteLine("Front door: guests can't unlock it");
            return;
        }
        real.Unlock();
    }
}
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: guests can't unlock it
Wall panel, as Maya:
Front door: unlocked
```

```java
interface Lock { void lock(); void unlock(); }

class FrontDoor implements Lock {
    public void lock() { IO.println("Front door: locked"); }
    public void unlock() { IO.println("Front door: unlocked"); }
}

// The stand-in at the door: the same promise, with the check in front of it.
class GuardedLock implements Lock {
    private final Lock real;
    private final String person;

    GuardedLock(Lock real, String person) {
        this.real = real;
        this.person = person;
    }

    public void lock() { real.lock(); }

    public void unlock() {
        if (person.equals("guest")) {
            IO.println("Front door: guests can't unlock it");
            return;
        }
        real.unlock();
    }
}

FrontDoor door = new FrontDoor();

// Every caller gets a lock made for the person using it.
Lock lockFor(String person) { return new GuardedLock(door, person); }

void phoneAppUnlock(String person) { IO.println("Phone app, as " + person + ":"); lockFor(person).unlock(); }
void voiceUnlock(String person) { IO.println("Voice, as " + person + ":"); lockFor(person).unlock(); }
void wallPanelUnlock(String person) { IO.println("Wall panel, as " + person + ":"); lockFor(person).unlock(); }

void main() {
    phoneAppUnlock("guest");
    voiceUnlock("guest");
    wallPanelUnlock("guest");
    wallPanelUnlock("Maya");
}
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: guests can't unlock it
Wall panel, as Maya:
Front door: unlocked
```

```python
class FrontDoor:
    def lock(self):
        print("Front door: locked")

    def unlock(self):
        print("Front door: unlocked")


class GuardedLock:
    """The stand-in at the door: the same promise, with the check in front of it."""

    def __init__(self, real, person):
        self.real = real
        self.person = person

    def lock(self):
        self.real.lock()

    def unlock(self):
        if self.person == "guest":
            print("Front door: guests can't unlock it")
            return
        self.real.unlock()


door = FrontDoor()


def lock_for(person):
    """Every caller gets a lock made for the person using it."""
    return GuardedLock(door, person)


def phone_app_unlock(person):
    print(f"Phone app, as {person}:")
    lock_for(person).unlock()


def voice_unlock(person):
    print(f"Voice, as {person}:")
    lock_for(person).unlock()


def wall_panel_unlock(person):
    print(f"Wall panel, as {person}:")
    lock_for(person).unlock()


phone_app_unlock("guest")
voice_unlock("guest")
wall_panel_unlock("guest")
wall_panel_unlock("Maya")
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: guests can't unlock it
Wall panel, as Maya:
Front door: unlocked
```

```javascript
class FrontDoor {
  lock() { console.log("Front door: locked"); }
  unlock() { console.log("Front door: unlocked"); }
}

// The stand-in at the door: the same promise, with the check in front of it.
class GuardedLock {
  #real;
  #person;

  constructor(real, person) {
    this.#real = real;
    this.#person = person;
  }

  lock() { this.#real.lock(); }

  unlock() {
    if (this.#person === "guest") {
      console.log("Front door: guests can't unlock it");
      return;
    }
    this.#real.unlock();
  }
}

const door = new FrontDoor();

// Every caller gets a lock made for the person using it.
const lockFor = (person) => new GuardedLock(door, person);

function phoneAppUnlock(person) { console.log(`Phone app, as ${person}:`); lockFor(person).unlock(); }
function voiceUnlock(person) { console.log(`Voice, as ${person}:`); lockFor(person).unlock(); }
function wallPanelUnlock(person) { console.log(`Wall panel, as ${person}:`); lockFor(person).unlock(); }

phoneAppUnlock("guest");
voiceUnlock("guest");
wallPanelUnlock("guest");
wallPanelUnlock("Maya");
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: guests can't unlock it
Wall panel, as Maya:
Front door: unlocked
```

```typescript
// A module of its own (export {}), so this Lock isn't mixed up with the browser's built-in Lock type.
export {};

interface Lock { lock(): void; unlock(): void; }

class FrontDoor implements Lock {
  lock(): void { console.log("Front door: locked"); }
  unlock(): void { console.log("Front door: unlocked"); }
}

// The stand-in at the door: the same promise, with the check in front of it.
class GuardedLock implements Lock {
  private readonly real: Lock;
  private readonly person: string;

  constructor(real: Lock, person: string) {
    this.real = real;
    this.person = person;
  }

  lock(): void { this.real.lock(); }

  unlock(): void {
    if (this.person === "guest") {
      console.log("Front door: guests can't unlock it");
      return;
    }
    this.real.unlock();
  }
}

const door = new FrontDoor();

// Every caller gets a lock made for the person using it.
const lockFor = (person: string): Lock => new GuardedLock(door, person);

function phoneAppUnlock(person: string): void { console.log(`Phone app, as ${person}:`); lockFor(person).unlock(); }
function voiceUnlock(person: string): void { console.log(`Voice, as ${person}:`); lockFor(person).unlock(); }
function wallPanelUnlock(person: string): void { console.log(`Wall panel, as ${person}:`); lockFor(person).unlock(); }

phoneAppUnlock("guest");
voiceUnlock("guest");
wallPanelUnlock("guest");
wallPanelUnlock("Maya");
```

```text
Phone app, as guest:
Front door: guests can't unlock it
Voice, as guest:
Front door: guests can't unlock it
Wall panel, as guest:
Front door: guests can't unlock it
Wall panel, as Maya:
Front door: unlocked
```

The sixth line says no now, and nobody fixed the wall panel's check: it never had one, and doesn't need one. The rule lives in one place, `GuardedLock`, and the three controls became one line each. The smartwatch app gets the rule the moment it's handed a lock, and the back door's lock gets it by being wrapped in a `GuardedLock` of its own.

Notice what the proxy *doesn't* do. It doesn't change the lock's shape (that was the adapter's job), and it doesn't add a new feature to locking. It only decides whether a call gets through.

## Two more stand-ins

The same shape, an object that keeps the real one's interface and stands in front of it, turns up for two other reasons. Teams name a proxy by what it controls:

| Kind | What it controls | In the hub |
|---|---|---|
| **Protection proxy** | *who* may make a call | `GuardedLock`: a guest can't unlock the front door |
| **Virtual proxy** | *when* the real object is made, so slow or big work waits until someone needs it | SkyCast's ten-day forecast is big; a stand-in fetches it the first time someone opens it, like the photo app's thumbnail |
| **Remote proxy** | *where* the real object lives: far away, on another computer | the hub's SkyCast client: the hub calls `today()` on an object in the hub, and the client asks SkyCast over the internet |

The remote proxy is one you use all the time. A *client* for a web service (an **API**, a set of calls one program offers another) is an object with ordinary methods, and behind each method it sends a request across the internet and waits for the answer. Here is the idea in Python, with the popular `requests` library; it isn't run here, because it would call a real address:

```python
import requests


class SkyCastClient:
    """Stands in for SkyCast: an ordinary method here, a request across the internet behind it."""

    def today(self):
        reply = requests.get("https://skycast.example/today", timeout=5)
        return reply.json()["summary"]
```

The hub calls `client.today()` as if SkyCast lived inside the hub. That's the whole point, and also the danger: a call that looks like it takes no time can take two seconds, or fail. The next lessons wrap this client to make it faster, and the next chapter keeps the hub working when SkyCast is down.

## How it got its name

A *proxy* is someone who acts for someone else: you can vote by proxy, or send a proxy to a meeting. Teams kept putting a stand-in object in front of the real one, to guard it, to put off making it, or to reach it across a network, so the 1994 book named it the **Proxy pattern**. The real object behind it is called the *real subject*. Checking who may do something is called **authorization**, and a protection proxy is one of the simplest ways to give it a home.

Proxy has no shorter "modern" version in most languages: it's already one small class with the same interface. JavaScript is the exception, below.

## Where you've already used it

- JavaScript's built-in `Proxy` makes a stand-in for any object, with a function that runs on every property read or write. Vue uses it to notice every change you make.
- Entity Framework and Hibernate can load a customer's orders only when your code first reads them: the orders you get back are virtual proxies.
- Every web service client (`HttpClient` wrappers in C#, a generated Java client, Python's SDKs for cloud services) is a remote proxy.
- A web page's `<img loading="lazy">` waits to load a picture until it's about to scroll into view, the virtual proxy's idea built into the browser.

## When not to use it

- **When there's one caller.** If only one screen ever unlocks the door, the check can live there. A proxy earns its place when there are several ways in.
- **When the check belongs to the object itself.** A lock that must never open while the alarm is set has a rule about locking, not about callers; that belongs in the lock.
- **When the delay or the distance should be visible.** A remote proxy makes a slow call look like a fast one. Where it matters, name it (`fetchToday()`, not `today()`), so callers know to expect a wait.

The cost is one class per thing you guard, and one more hop between the caller and the real object.

**How often you'll meet it:** every day (our estimate: you'll mostly meet proxies made for you, by web clients and data libraries, and write protection proxies now and then).

## Check yourself

2 questions to try on the lesson page.

## So what

When every way in to an object needs the same check, or the same "not yet", don't copy it into every caller. Put a stand-in at the door, with the same interface, and let it decide what gets through.

## Key terms

- [Proxy Pattern](https://www.ask-codey.com/glossary/proxy-pattern)
- [Authorization](https://www.ask-codey.com/glossary/authorization)
- [API](https://www.ask-codey.com/glossary/api)

## Cheat sheets

- [Proxy: The Stand-In at the Door](https://www.ask-codey.com/cheat-sheets/dp-proxy-cheat-sheet)

Source: https://www.ask-codey.com/lessons/dp-proxy
