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
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:
FrontDoor door = new FrontDoor();
PhoneAppUnlock("guest");
VoiceUnlock("guest");
WallPanelUnlock("guest");
WallPanelUnlock("Maya");
void PhoneAppUnlock(string person)
{
Console.WriteLine( quot;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( quot;Voice, as {person}:");
if (person == "guest") { Console.WriteLine("Front door: guests can't unlock it"); return; }
door.Unlock();
}
void WallPanelUnlock(string person)
{
Console.WriteLine( quot;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");
}
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
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");
}
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
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")
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
// 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");
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
// 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");
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.

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:

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( quot;Phone app, as {person}:"); LockFor(person).Unlock(); }
void VoiceUnlock(string person) { Console.WriteLine( quot;Voice, as {person}:"); LockFor(person).Unlock(); }
void WallPanelUnlock(string person) { Console.WriteLine( quot;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();
}
}
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
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");
}
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
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")
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
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");
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
// 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");
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:
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
Proxymakes 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 (
HttpClientwrappers 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(), nottoday()), 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.