Composition Access, delegation, and cached copies

Proxy

A familiar door. A decision before it opens.

Your project archive holds a brand guide and an unreleased launch plan. Ari can read both. Bo can read the guide. The document viewer asks for a document and renders the result.

Now add a cache. Ari opens the launch plan, leaving a copy ready for the next request. Bo asks for it. The archive no longer needs to be contacted—but does Bo get the document?

TypeScriptGoPythonOne reading contract · across the comparison

01 / Give the caller a stand-in

The viewer still asks to read.

A direct archive reader is a reasonable starting point for trusted internal code. It accepts a document ID and returns the document or an error. Once different readers need different access, a check before each call seems like a small addition.

Then a preview endpoint appears, followed by an export action. Each caller needs the same rule. Add caching at one call site and it becomes easy to return a saved document before reaching the permission check.

A proxy is a stand-in that offers the interface a caller expects while controlling access to another object or resource. Here, both the archive and its proxy implement DocumentReader.read(request). Give the viewer the proxy as its reader. The viewer keeps its ordinary read call; the proxy decides whether to refuse, return a cached copy, or ask the archive.

We will build a protection proxy, then add caching. The archive holds three local records, and reader identities and grants are simulated, so every permission check and archive read stays visible.

01 / CALLER → PROXY

Document viewer

Asks its reader for a document. Handles success or a returned error.

02 / PROXY → ARCHIVE

Archive proxy

Checks current access. Reuses a successful copy or forwards an allowed miss.

03 / ARCHIVE → PROXY → CALLER

Internal archive

Owns the source records. Returns a document copy or an archive error.

02 / Follow the order

Having the document does not answer who may read it.

The proxy checks the reader’s current grant before looking in its cache. A denial ends the request there. An allowed hit returns a copy. An allowed miss reaches the archive and saves the result only when it succeeds.

The cache belongs to this proxy instance and is shared across its readers. It uses the exact document ID as its key because every authorized reader receives the same content. Ari and Bo can reuse one cached brand guide; Bo still cannot read Ari’s cached launch plan.

Four launch-plan reads through one proxy, in order
Request	Current access	Result	New archive reads
Ari opens it	Allowed	Fetch and cache the plan	1
Ari opens it again	Allowed	Cached plan	0
Bo opens it	Denied	Forbidden, despite the cache	0
Revoke Ari’s grant; Ari tries again	Denied	Forbidden, despite the cache	0

Four permission checks. One cache hit. One archive read. Revoking access changes the next read even though the cached plan remains. It cannot erase a copy Ari already received.

“Same interface” gives the caller a stable way to ask and handle the answer. It does not promise identical timing, freshness, or permission outcomes to the raw archive. Those behaviors are part of the reader’s contract too.

03 / Read the shape

One reader contract, two implementations.

Start with the basic protection wrapper: deny or forward. In the practical form, follow the permission check past the cache lookup to the origin read. The call-site view shows the trusted owner wiring these objects together and passing the proxy to showDocument.

That caller prints either the document body or the returned error. It needs no “is this a proxy?” branch. Complete files include the records, mutable access rules, archive, and example invocation. Every comparison program runs the four requests from the table.

Read in

Compare with

The archive and protection proxy satisfy one DocumentReader contract. The proxy either refuses the read or forwards the same request. Supporting records and policy types appear in the complete file.

TypeScriptReading

archive.ts

export interface DocumentReader {
	read(request: ReadRequest): ReadResult;
}
export class ProtectionProxy implements DocumentReader {
	#origin: DocumentReader;
	#rules: AccessRules;
	constructor(origin: DocumentReader, rules: AccessRules) {
		this.#origin = origin;
		this.#rules = rules;
	}
	read(request: ReadRequest): ReadResult {
		if (!this.#rules.canRead(request.actor, request.id)) return { ok: false, error: 'forbidden' };
		return this.#origin.read(request);
	}
}

GoAlongside

archive.go

type DocumentReader interface {
	Read(ReadRequest) (Document, error)
}
type ProtectionProxy struct {
	origin DocumentReader
	rules  *AccessRules
}

func (p *ProtectionProxy) Read(request ReadRequest) (Document, error) {
	if !p.rules.CanRead(request.Actor, request.ID) {
		return Document{}, errors.New("forbidden")
	}
	return p.origin.Read(request)
}

Read complete examples without JavaScript

archive.ts

export type DocumentRecord = Readonly<{ id: string; title: string; body: string }>;
// actor is supplied by a trusted application boundary, not accepted as proof of identity.
export type ReadRequest = Readonly<{ actor: string; id: string }>;
export type ReadResult = Readonly<
	| { ok: true; document: DocumentRecord }
	| { ok: false; error: 'forbidden' | 'not found' | 'archive offline' }
>;
export class AccessRules {
	#grants = new Map<string, Set<string>>();
	allow(actor: string, id: string): void {
		const ids = this.#grants.get(actor) ?? new Set<string>();
		ids.add(id);
		this.#grants.set(actor, ids);
	}
	revoke(actor: string, id: string): void {
		this.#grants.get(actor)?.delete(id);
	}
	canRead(actor: string, id: string): boolean {
		return this.#grants.get(actor)?.has(id) ?? false;
	}
}

export interface DocumentReader {
	read(request: ReadRequest): ReadResult;
}
export class ProtectionProxy implements DocumentReader {
	#origin: DocumentReader;
	#rules: AccessRules;
	constructor(origin: DocumentReader, rules: AccessRules) {
		this.#origin = origin;
		this.#rules = rules;
	}
	read(request: ReadRequest): ReadResult {
		if (!this.#rules.canRead(request.actor, request.id)) return { ok: false, error: 'forbidden' };
		return this.#origin.read(request);
	}
}

export class Archive implements DocumentReader {
	#documents: Map<string, DocumentRecord>;
	#offline = false;
	#reads = 0;
	constructor(documents: readonly DocumentRecord[]) {
		this.#documents = new Map(documents.map((document) => [document.id, { ...document }]));
	}
	read(request: ReadRequest): ReadResult {
		this.#reads++;
		if (this.#offline) return { ok: false, error: 'archive offline' };
		const document = this.#documents.get(request.id);
		return document ? { ok: true, document: { ...document } } : { ok: false, error: 'not found' };
	}
	setOffline(value: boolean): void {
		this.#offline = value;
	}
	update(id: string, body: string): boolean {
		const document = this.#documents.get(id);
		if (!document) return false;
		this.#documents.set(id, { ...document, body });
		return true;
	}
	get reads(): number {
		return this.#reads;
	}
}

export class ArchiveProxy implements DocumentReader {
	#cache = new Map<string, DocumentRecord>();
	#checks = 0;
	#hits = 0;
	#origin: DocumentReader;
	#rules: AccessRules;
	constructor(origin: DocumentReader, rules: AccessRules) {
		this.#origin = origin;
		this.#rules = rules;
	}
	read(request: ReadRequest): ReadResult {
		this.#checks++;
		if (!this.#rules.canRead(request.actor, request.id)) return { ok: false, error: 'forbidden' };
		// Authorization comes before every cache lookup, including a warm document.
		const cached = this.#cache.get(request.id);
		if (cached) {
			this.#hits++;
			return { ok: true, document: { ...cached } };
		}
		const result = this.#origin.read(request);
		if (!result.ok) return result; // Failed reads are not cached.
		this.#cache.set(request.id, { ...result.document });
		return { ok: true, document: { ...result.document } };
	}
	clear(): void {
		this.#cache.clear();
	}
	stats() {
		return { checks: this.#checks, hits: this.#hits, entries: this.#cache.size };
	}
}

export const documents: readonly DocumentRecord[] = [
	{ id: 'guide', title: 'Brand guide', body: 'Use cobalt for primary actions.' },
	{ id: 'launch', title: 'Launch plan', body: 'Preview opens Monday.' },
	{ id: 'empty', title: 'Empty note', body: '' }
];
export function defaultRules(): AccessRules {
	const rules = new AccessRules();
	for (const document of documents) rules.allow('ari', document.id);
	rules.allow('bo', 'guide');
	return rules;
}
export function showDocument(reader: DocumentReader, request: ReadRequest): void {
	const result = reader.read(request);
	console.log(`${request.actor}/${request.id}: ${result.ok ? result.document.body : result.error}`);
}
export function runExample(): void {
	// Trusted composition owns the raw archive and policy. The caller receives a Reader.
	const origin = new Archive(documents),
		rules = defaultRules();
	const proxy = new ArchiveProxy(origin, rules);
	showDocument(proxy, { actor: 'ari', id: 'launch' });
	showDocument(proxy, { actor: 'ari', id: 'launch' });
	showDocument(proxy, { actor: 'bo', id: 'launch' });
	rules.revoke('ari', 'launch');
	showDocument(proxy, { actor: 'ari', id: 'launch' });
	console.log(
		`checks=${proxy.stats().checks} cache hits=${proxy.stats().hits} archive reads=${origin.reads}`
	);
}

runExample();

archive.go

package main

import (
	"errors"
	"fmt"
)

type Document struct{ ID, Title, Body string }

// Actor is a trusted application identity, not proof supplied by a browser.
type ReadRequest struct{ Actor, ID string }
type AccessRules struct{ grants map[string]map[string]bool }

func NewRules() *AccessRules { return &AccessRules{grants: map[string]map[string]bool{}} }
func (r *AccessRules) Allow(actor, id string) {
	if r.grants[actor] == nil {
		r.grants[actor] = map[string]bool{}
	}
	r.grants[actor][id] = true
}
func (r *AccessRules) Revoke(actor, id string)       { delete(r.grants[actor], id) }
func (r *AccessRules) CanRead(actor, id string) bool { return r.grants[actor][id] }

type DocumentReader interface {
	Read(ReadRequest) (Document, error)
}
type ProtectionProxy struct {
	origin DocumentReader
	rules  *AccessRules
}

func (p *ProtectionProxy) Read(request ReadRequest) (Document, error) {
	if !p.rules.CanRead(request.Actor, request.ID) {
		return Document{}, errors.New("forbidden")
	}
	return p.origin.Read(request)
}


type Archive struct {
	documents map[string]Document
	offline   bool
	reads     int
}

func NewArchive(documents []Document) *Archive {
	a := &Archive{documents: map[string]Document{}}
	for _, document := range documents {
		a.documents[document.ID] = document
	}
	return a
}
func (a *Archive) Read(request ReadRequest) (Document, error) {
	a.reads++
	if a.offline {
		return Document{}, errors.New("archive offline")
	}
	document, ok := a.documents[request.ID]
	if !ok {
		return Document{}, errors.New("not found")
	}
	return document, nil
}
func (a *Archive) SetOffline(value bool) { a.offline = value }
func (a *Archive) Update(id, body string) bool {
	document, ok := a.documents[id]
	if !ok {
		return false
	}
	document.Body = body
	a.documents[id] = document
	return true
}
func (a *Archive) Reads() int { return a.reads }

type ProxyStats struct{ Checks, Hits, Entries int }
type ArchiveProxy struct {
	origin       DocumentReader
	rules        *AccessRules
	cache        map[string]Document
	checks, hits int
}

func NewProxy(origin DocumentReader, rules *AccessRules) *ArchiveProxy {
	return &ArchiveProxy{origin: origin, rules: rules, cache: map[string]Document{}}
}
func (p *ArchiveProxy) Read(request ReadRequest) (Document, error) {
	p.checks++
	if !p.rules.CanRead(request.Actor, request.ID) {
		return Document{}, errors.New("forbidden")
	}
	// Check current access before looking at any shared cached copy.
	if document, ok := p.cache[request.ID]; ok {
		p.hits++
		return document, nil
	}
	document, err := p.origin.Read(request)
	if err != nil {
		return Document{}, err
	}
	p.cache[request.ID] = document // Cache only success; an empty Body is still valid.
	return document, nil
}
func (p *ArchiveProxy) Clear() { p.cache = map[string]Document{} }
func (p *ArchiveProxy) Stats() ProxyStats {
	return ProxyStats{Checks: p.checks, Hits: p.hits, Entries: len(p.cache)}
}


func Documents() []Document {
	return []Document{
		{ID: "guide", Title: "Brand guide", Body: "Use cobalt for primary actions."},
		{ID: "launch", Title: "Launch plan", Body: "Preview opens Monday."},
		{ID: "empty", Title: "Empty note", Body: ""},
	}
}
func DefaultRules() *AccessRules {
	rules := NewRules()
	for _, document := range Documents() {
		rules.Allow("ari", document.ID)
	}
	rules.Allow("bo", "guide")
	return rules
}
func ShowDocument(reader DocumentReader, request ReadRequest) {
	document, err := reader.Read(request)
	message := document.Body
	if err != nil {
		message = err.Error()
	}
	fmt.Printf("%s/%s: %s\n", request.Actor, request.ID, message)
}
func main() {
	origin, rules := NewArchive(Documents()), DefaultRules()
	proxy := NewProxy(origin, rules)
	ShowDocument(proxy, ReadRequest{Actor: "ari", ID: "launch"})
	ShowDocument(proxy, ReadRequest{Actor: "ari", ID: "launch"})
	ShowDocument(proxy, ReadRequest{Actor: "bo", ID: "launch"})
	rules.Revoke("ari", "launch")
	ShowDocument(proxy, ReadRequest{Actor: "ari", ID: "launch"})
	fmt.Printf("checks=%d cache hits=%d archive reads=%d\n", proxy.Stats().Checks, proxy.Stats().Hits, origin.Reads())
}

archive.py

"""Mediate access to an archive while preserving the document-reader contract."""

from dataclasses import dataclass
from typing import Literal, Protocol


@dataclass
class DocumentRecord:
    id: str
    title: str
    body: str


@dataclass(frozen=True)
class ReadRequest:
    actor: str
    id: str


@dataclass
class ReadSuccess:
    document: DocumentRecord


@dataclass(frozen=True)
class ReadFailure:
    error: Literal["forbidden", "not found", "archive offline"]


ReadResult = ReadSuccess | ReadFailure


class AccessRules:
    def __init__(self) -> None:
        self._grants: dict[str, set[str]] = {}

    def allow(self, actor: str, document_id: str) -> None:
        self._grants.setdefault(actor, set()).add(document_id)

    def revoke(self, actor: str, document_id: str) -> None:
        self._grants.get(actor, set()).discard(document_id)

    def can_read(self, actor: str, document_id: str) -> bool:
        return document_id in self._grants.get(actor, set())


class DocumentReader(Protocol):
    def read(self, request: ReadRequest) -> ReadResult: ...


class ProtectionProxy:
    def __init__(self, origin: DocumentReader, rules: AccessRules) -> None:
        self._origin = origin
        self._rules = rules

    def read(self, request: ReadRequest) -> ReadResult:
        if not self._rules.can_read(request.actor, request.id):
            return ReadFailure("forbidden")
        return self._origin.read(request)



class Archive:
    def __init__(self, documents: list[DocumentRecord]) -> None:
        self._documents = {document.id: self._copy(document) for document in documents}
        self._offline = False
        self._reads = 0

    def read(self, request: ReadRequest) -> ReadResult:
        self._reads += 1
        if self._offline:
            return ReadFailure("archive offline")
        document = self._documents.get(request.id)
        return ReadFailure("not found") if document is None else ReadSuccess(self._copy(document))

    def set_offline(self, value: bool) -> None:
        self._offline = value

    def update(self, document_id: str, body: str) -> bool:
        document = self._documents.get(document_id)
        if document is None:
            return False
        self._documents[document_id] = DocumentRecord(document.id, document.title, body)
        return True

    @property
    def reads(self) -> int:
        return self._reads

    @staticmethod
    def _copy(document: DocumentRecord) -> DocumentRecord:
        return DocumentRecord(document.id, document.title, document.body)


@dataclass(frozen=True)
class ProxyStats:
    checks: int
    hits: int
    entries: int


class ArchiveProxy:
    def __init__(self, origin: DocumentReader, rules: AccessRules) -> None:
        self._origin = origin
        self._rules = rules
        self._cache: dict[str, DocumentRecord] = {}
        self._checks = 0
        self._hits = 0

    def read(self, request: ReadRequest) -> ReadResult:
        self._checks += 1
        if not self._rules.can_read(request.actor, request.id):
            return ReadFailure("forbidden")
        # Current permission is checked before every cache lookup.
        cached = self._cache.get(request.id)
        if cached is not None:
            self._hits += 1
            return ReadSuccess(Archive._copy(cached))
        result = self._origin.read(request)
        if isinstance(result, ReadFailure):
            return result
        self._cache[request.id] = Archive._copy(result.document)
        return ReadSuccess(Archive._copy(result.document))

    def clear(self) -> None:
        self._cache.clear()

    def stats(self) -> ProxyStats:
        return ProxyStats(self._checks, self._hits, len(self._cache))



documents: list[DocumentRecord] = [
    DocumentRecord("guide", "Brand guide", "Use cobalt for primary actions."),
    DocumentRecord("launch", "Launch plan", "Preview opens Monday."),
    DocumentRecord("empty", "Empty note", ""),
]


def default_rules() -> AccessRules:
    rules = AccessRules()
    for document in documents:
        rules.allow("ari", document.id)
    rules.allow("bo", "guide")
    return rules


def show_document(reader: DocumentReader, request: ReadRequest) -> None:
    result = reader.read(request)
    message = result.document.body if isinstance(result, ReadSuccess) else result.error
    print(f"{request.actor}/{request.id}: {message}")


def run_example() -> None:
    origin = Archive(documents)
    rules = default_rules()
    proxy = ArchiveProxy(origin, rules)
    show_document(proxy, ReadRequest("ari", "launch"))
    show_document(proxy, ReadRequest("ari", "launch"))
    show_document(proxy, ReadRequest("bo", "launch"))
    rules.revoke("ari", "launch")
    show_document(proxy, ReadRequest("ari", "launch"))
    stats = proxy.stats()
    print(f"checks={stats.checks} cache hits={stats.hits} archive reads={origin.reads}")




if __name__ == "__main__":
    run_example()

ProxyExample.java

import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

record DocumentRecord(String id, String title, String body) {}
record ReadRequest(String actor, String id) {}

sealed interface ReadResult permits ReadSuccess, ReadFailure {}

record ReadSuccess(DocumentRecord document) implements ReadResult {}
record ReadFailure(String error) implements ReadResult {}

final class AccessRules {
    private final Map<String, Set<String>> grants = new HashMap<>();

    void allow(String actor, String id) {
        grants.computeIfAbsent(actor, ignored -> new HashSet<>()).add(id);
    }

    void revoke(String actor, String id) {
        Set<String> ids = grants.get(actor);
        if (ids != null) ids.remove(id);
    }

    boolean canRead(String actor, String id) {
        return grants.getOrDefault(actor, Set.of()).contains(id);
    }
}

interface DocumentReader {
    ReadResult read(ReadRequest request);
}

final class ProtectionProxy implements DocumentReader {
    private final DocumentReader origin;
    private final AccessRules rules;

    ProtectionProxy(DocumentReader origin, AccessRules rules) {
        this.origin = origin;
        this.rules = rules;
    }

    @Override
    public ReadResult read(ReadRequest request) {
        if (!rules.canRead(request.actor(), request.id())) return new ReadFailure("forbidden");
        return origin.read(request);
    }
}

final class Archive implements DocumentReader {
    private final Map<String, DocumentRecord> documents = new HashMap<>();
    private boolean offline;
    private int reads;

    Archive(List<DocumentRecord> source) {
        for (DocumentRecord document : source) documents.put(document.id(), copy(document));
    }

    @Override
    public ReadResult read(ReadRequest request) {
        reads++;
        if (offline) return new ReadFailure("archive offline");
        DocumentRecord document = documents.get(request.id());
        return document == null ? new ReadFailure("not found") : new ReadSuccess(copy(document));
    }

    void setOffline(boolean value) {
        offline = value;
    }

    boolean update(String id, String body) {
        DocumentRecord document = documents.get(id);
        if (document == null) return false;
        documents.put(id, new DocumentRecord(document.id(), document.title(), body));
        return true;
    }

    int reads() {
        return reads;
    }

    static DocumentRecord copy(DocumentRecord document) {
        return new DocumentRecord(document.id(), document.title(), document.body());
    }
}

record ProxyStats(int checks, int hits, int entries) {}

final class ArchiveProxy implements DocumentReader {
    private final DocumentReader origin;
    private final AccessRules rules;
    private final Map<String, DocumentRecord> cache = new HashMap<>();
    private int checks;
    private int hits;

    ArchiveProxy(DocumentReader origin, AccessRules rules) {
        this.origin = origin;
        this.rules = rules;
    }

    @Override
    public ReadResult read(ReadRequest request) {
        checks++;
        if (!rules.canRead(request.actor(), request.id())) return new ReadFailure("forbidden");
        // Current permission is checked before every cache lookup.
        DocumentRecord cached = cache.get(request.id());
        if (cached != null) {
            hits++;
            return new ReadSuccess(Archive.copy(cached));
        }
        ReadResult result = origin.read(request);
        if (result instanceof ReadFailure) return result;
        DocumentRecord document = ((ReadSuccess) result).document();
        cache.put(request.id(), Archive.copy(document));
        return new ReadSuccess(Archive.copy(document));
    }

    void clear() {
        cache.clear();
    }

    ProxyStats stats() {
        return new ProxyStats(checks, hits, cache.size());
    }
}

final class Display {
    private Display() {}

    static String render(DocumentReader reader, ReadRequest request) {
        ReadResult result = reader.read(request);
        if (result instanceof ReadSuccess success) return request.actor() + "/" + request.id() + ": " + success.document().body();
        return request.actor() + "/" + request.id() + ": " + ((ReadFailure) result).error();
    }
}

public final class ProxyExample {
    private ProxyExample() {}

    static List<DocumentRecord> documents() {
        return List.of(
            new DocumentRecord("guide", "Brand guide", "Use cobalt for primary actions."),
            new DocumentRecord("launch", "Launch plan", "Preview opens Monday."),
            new DocumentRecord("empty", "Empty note", "")
        );
    }

    static AccessRules defaultRules() {
        AccessRules rules = new AccessRules();
        for (DocumentRecord document : documents()) rules.allow("ari", document.id());
        rules.allow("bo", "guide");
        return rules;
    }

    static List<String> runExample() {
        Archive origin = new Archive(documents());
        AccessRules rules = defaultRules();
        ArchiveProxy proxy = new ArchiveProxy(origin, rules);
        List<String> output = new ArrayList<>();
        output.add(Display.render(proxy, new ReadRequest("ari", "launch")));
        output.add(Display.render(proxy, new ReadRequest("ari", "launch")));
        output.add(Display.render(proxy, new ReadRequest("bo", "launch")));
        rules.revoke("ari", "launch");
        output.add(Display.render(proxy, new ReadRequest("ari", "launch")));
        ProxyStats stats = proxy.stats();
        output.add("checks=" + stats.checks() + " cache hits=" + stats.hits() + " archive reads=" + origin.reads());
        return output;
    }

    public static void main(String[] args) {
        for (String line : runExample()) System.out.println(line);
    }
}

archive.rs

use std::cell::RefCell;
use std::collections::{HashMap, HashSet};
use std::rc::Rc;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Document {
    pub id: String,
    pub title: String,
    pub body: String,
}
// Actor comes from a trusted application boundary, not a browser identity claim.
pub struct ReadRequest<'a> {
    pub actor: &'a str,
    pub id: &'a str,
}
#[derive(Default)]
pub struct AccessRules {
    grants: HashMap<String, HashSet<String>>,
}
impl AccessRules {
    pub fn allow(&mut self, actor: &str, id: &str) {
        self.grants
            .entry(actor.to_owned())
            .or_default()
            .insert(id.to_owned());
    }
    pub fn revoke(&mut self, actor: &str, id: &str) {
        if let Some(ids) = self.grants.get_mut(actor) {
            ids.remove(id);
        }
    }
    pub fn can_read(&self, actor: &str, id: &str) -> bool {
        self.grants.get(actor).is_some_and(|ids| ids.contains(id))
    }
}
pub trait DocumentReader {
    fn read(&mut self, request: &ReadRequest<'_>) -> Result<Document, &'static str>;
}
pub struct ProtectionProxy<R: DocumentReader> {
    origin: Rc<RefCell<R>>,
    rules: Rc<RefCell<AccessRules>>,
}
impl<R: DocumentReader> ProtectionProxy<R> {
    pub fn new(origin: Rc<RefCell<R>>, rules: Rc<RefCell<AccessRules>>) -> Self {
        Self { origin, rules }
    }
}
impl<R: DocumentReader> DocumentReader for ProtectionProxy<R> {
    fn read(&mut self, request: &ReadRequest<'_>) -> Result<Document, &'static str> {
        if !self.rules.borrow().can_read(request.actor, request.id) {
            return Err("forbidden");
        }
        self.origin.borrow_mut().read(request)
    }
}
pub struct Archive {
    documents: HashMap<String, Document>,
    offline: bool,
    reads: usize,
}
impl Archive {
    pub fn new(documents: Vec<Document>) -> Self {
        Self {
            documents: documents.into_iter().map(|d| (d.id.clone(), d)).collect(),
            offline: false,
            reads: 0,
        }
    }
    pub fn set_offline(&mut self, value: bool) {
        self.offline = value;
    }
    pub fn update(&mut self, id: &str, body: &str) -> bool {
        if let Some(document) = self.documents.get_mut(id) {
            document.body = body.to_owned();
            true
        } else {
            false
        }
    }
    pub fn reads(&self) -> usize {
        self.reads
    }
}
impl DocumentReader for Archive {
    fn read(&mut self, request: &ReadRequest<'_>) -> Result<Document, &'static str> {
        self.reads += 1;
        if self.offline {
            return Err("archive offline");
        }
        self.documents.get(request.id).cloned().ok_or("not found")
    }
}
#[derive(Debug, PartialEq, Eq)]
pub struct ProxyStats {
    pub checks: usize,
    pub hits: usize,
    pub entries: usize,
}
pub struct ArchiveProxy<R: DocumentReader> {
    origin: Rc<RefCell<R>>,
    rules: Rc<RefCell<AccessRules>>,
    cache: HashMap<String, Document>,
    checks: usize,
    hits: usize,
}
impl<R: DocumentReader> ArchiveProxy<R> {
    pub fn new(origin: Rc<RefCell<R>>, rules: Rc<RefCell<AccessRules>>) -> Self {
        Self {
            origin,
            rules,
            cache: HashMap::new(),
            checks: 0,
            hits: 0,
        }
    }
    pub fn clear(&mut self) {
        self.cache.clear();
    }
    pub fn stats(&self) -> ProxyStats {
        ProxyStats {
            checks: self.checks,
            hits: self.hits,
            entries: self.cache.len(),
        }
    }
}
impl<R: DocumentReader> DocumentReader for ArchiveProxy<R> {
    fn read(&mut self, request: &ReadRequest<'_>) -> Result<Document, &'static str> {
        self.checks += 1;
        if !self.rules.borrow().can_read(request.actor, request.id) {
            return Err("forbidden");
        }
        // A cached copy does not bypass today's permission check.
        if let Some(document) = self.cache.get(request.id) {
            self.hits += 1;
            return Ok(document.clone());
        }
        let document = self.origin.borrow_mut().read(request)?;
        self.cache.insert(request.id.to_owned(), document.clone());
        Ok(document)
    }
}
pub fn documents() -> Vec<Document> {
    [
        ("guide", "Brand guide", "Use cobalt for primary actions."),
        ("launch", "Launch plan", "Preview opens Monday."),
        ("empty", "Empty note", ""),
    ]
    .into_iter()
    .map(|(id, title, body)| Document {
        id: id.to_owned(),
        title: title.to_owned(),
        body: body.to_owned(),
    })
    .collect()
}
pub fn default_rules() -> AccessRules {
    let mut rules = AccessRules::default();
    for document in documents() {
        rules.allow("ari", &document.id);
    }
    rules.allow("bo", "guide");
    rules
}
pub fn show_document(reader: &mut dyn DocumentReader, request: ReadRequest<'_>) {
    let message = match reader.read(&request) {
        Ok(document) => document.body,
        Err(error) => error.to_owned(),
    };
    println!("{}/{}: {}", request.actor, request.id, message);
}
fn main() {
    let origin = Rc::new(RefCell::new(Archive::new(documents())));
    let rules = Rc::new(RefCell::new(default_rules()));
    let mut proxy = ArchiveProxy::new(Rc::clone(&origin), Rc::clone(&rules));
    show_document(
        &mut proxy,
        ReadRequest {
            actor: "ari",
            id: "launch",
        },
    );
    show_document(
        &mut proxy,
        ReadRequest {
            actor: "ari",
            id: "launch",
        },
    );
    show_document(
        &mut proxy,
        ReadRequest {
            actor: "bo",
            id: "launch",
        },
    );
    rules.borrow_mut().revoke("ari", "launch");
    show_document(
        &mut proxy,
        ReadRequest {
            actor: "ari",
            id: "launch",
        },
    );
    println!(
        "checks={} cache hits={} archive reads={}",
        proxy.stats().checks,
        proxy.stats().hits,
        origin.borrow().reads()
    );
}

Reading the TypeScript

implements DocumentReader makes the shared shape explicit. TypeScript interfaces are structural: a compatible read method satisfies this contract. The ok field distinguishes a document from an expected failure before the caller reads the corresponding fields.

A cache entry is a document object, so an empty body still counts as a hit. Object spreads copy the record into and out of the cache. All fields here are strings; this shallow copy is sufficient for these records. Adding a nested mutable object would require revisiting that boundary.

The # fields, such as #cache and #rules, stay inside their instance. Type annotations and private fields do not turn an in-browser object into an authorization service; the real boundary still belongs on the server.

Reading the Go

DocumentReader is satisfied implicitly by a matching Read method. The caller accepts the interface; constructors return pointers to concrete implementations. Pointer receivers let repeated reads update the same cache and counters.

The map lookup’s ok reports presence independently of the body’s contents. Returning a Document copies its string fields, while the second return value carries an error. These maps and counters are used sequentially, without goroutine synchronization.

Reading the PythonProtocols, dataclasses, and explicit copies

Python’s Protocol describes the reader contract without a shared base class. The result is a small union of success and failure objects, so the caller checks which answer it received before reading a document or error.

The archive and cache copy the mutable document dataclass at their boundaries. The proxy returns an authorized copy, while a failed origin result is returned unchanged and is not retained. Python’s annotations do not add synchronization to the maps.

04 / Predict, change, observe

Warm the cache. Change the reader.

Watch the recorded reads and revocation, or step through their results. In Try it, start with Ari and the launch plan. Predict a document and read it twice. Then select Bo without clearing the cache. Predict again. The path below the controls shows which step handled the latest request; the counters accumulate until reset.

Switch the proxy order to the deliberately broken cache-first version. This starts a fresh archive. Let Ari warm the launch plan, then let Bo ask for it. A cold denial can look correct while a warm cache quietly skips the check.

Playback controls

Proxy

A warm copy still needs permission.

ari / launchCurrent grant: allowed

1 / PermissionNot calledGrant present
2 / CacheNot called0 retained
3 / ArchiveNot calledOnline

Retained copies

Empty

Returned to callerNo current response

Read to inspect the result.

Checks 0Hits 0Reads 0

01/ 05

An empty cache

Permission comes first.

Ari can read the launch plan. No copy has been cached yet.

Reduced motion: choose a scene to see its completed state.

Read this scene

Ari can read the launch plan. No copy has been cached yet.

Current grant: allowed. Cached: none. Permission checks 0, cache hits 0, archive reads 0. Result: no current response.

Try the example by reading

Ari reads the launch plan from the archive, then from cache. Revoking Ari’s grant leaves the cached copy in place. The next read checks permission and returns forbidden without using it.

PROJECT ARCHIVE / ONE READING INTERFACE

A cached copy still needs permission.

Switching reader preserves the cache so you can test who receives a warm copy.

Proxy order

Reader

Document

Allow this reader to open this documentThis changes the model’s current policy without clearing the cache. Archive offlineCached content remains available to permitted readers.

What will the next read return?

ari / launchCurrent grant: allowed

1 / PermissionNot calledGrant present
2 / CacheNot called0 retained
3 / ArchiveNot calledOnline

Retained copies

Empty

Returned to callerNo current response

Read to inspect the result.

Checks 0Hits 0Reads 0

Read the launch plan as Ari, then switch to Bo and read it again. Bo starts without access; Ari’s cached copy should not change that.

Trace requests and policy changes

Most recent 16 actions. Switching the proxy order or resetting creates a fresh archive owner.

Try revocation too: warm a document as Ari, then uncheck Ari’s grant and read again. The guarded proxy denies the new request. The broken version keeps returning its copy. Changing permission need not delete content to stop future reads through a correctly ordered gate.

Finally, warm an allowed document and take the archive offline. The guarded cache can still serve that authorized read. Clear the cache and the next allowed read fails; a later attempt reaches the archive again because failures are not cached. The empty note is a successful document with an empty body, so it is cached normally.

The browser lab runs the TypeScript implementation above, plus a browser-only broken ordering for contrast; the other language files show the same reader contract natively.

05 / Review a decision

Trace the path that can return the document.

A check is useful only when every protected return path goes through it. Review the ordering, the references given to the caller, and the responsibility behind the wrapper.

06 / Give it a real job

The owner chooses which reader leaves the room.

Imagine a server endpoint behind a document viewer’s Open action. Authentication supplies the actor; the endpoint supplies the requested document ID. A trusted composition root—the code that assembles the service—owns the internal archive, current policy, and retained proxy. The endpoint receives the proxy as its reader.

The actor string in our example represents that trusted request context. Accepting an unchecked actor from a browser would let the caller choose whose permissions to use. Putting the archive data and the check in the browser also gives the user both sides of the gate.

If the preview or export path receives the raw archive, it can skip the proxy entirely. Keep that reader internal and ensure every protected entry point applies the policy. OWASP’s authorization guidance calls for checking authorization on every request and denying by default. Our placement before every cache return is an application of that rule. Read the authorization guidance.

Now the launch plan changes. Our cached body stays stale until clear(); that method drops copies without changing grants or historical counters. Content freshness and permission freshness are separate decisions. This example reads the current in-memory grant every time, but a real policy service can have its own stale data and failure modes.

Before this becomes a shared service

Define the cache’s identity and lifetime. Document ID is enough for our three shared records. If a response varies by workspace, revision, locale, or reader, the key or cache scope must include every value that changes the content. Keep the permission check even with a more specific key. Add capacity and freshness policies before retaining an open-ended archive.

Decide how failures age. This proxy retains only successful reads. Offline and missing-document results pass through and are retried on later allowed requests. That is easy to explain, but repeated failures can repeatedly load a real service. Any negative caching or retry policy needs an explicit lifetime and must preserve access checks.

Make concurrent behavior explicit. Two asynchronous misses could duplicate a fetch; mutable maps need protection in concurrent native code. A grant could change while a network read is in flight. Sharing pending work and deciding when authorization takes effect need their own design.

Count decisions as well as reads. The counters record exact calls. A real service may record allowed and denied decisions independently of origin reads. An authorized cache hit is still a read worth accounting for.

Build UIs?$state hands you a Proxy and React holds the object itself, and one day an integration will need a view of your state it cannot change.

Where it already is in your components

In Svelte you write todo.done = true and the row updates. In React you never write that; you give the setter a new object. Both habits come from whether a stand-in sits between you and your state. Svelte’s docs say that “If $state is used with an array or a simple object, the result is a deeply reactive state proxy.” It is a JavaScript Proxy offering your object’s own interface. Your assignment, or a todos.push(…), reaches its set trap, which records the value and updates whatever on the page read it.

Its limits follow from where it stands. $state hands you the proxy, not your object: in a Svelte 5.57 mount, $state(original) === original was false, and the development build warned that “proxies and the values they proxy have different identities.” Writing to original after the page rendered changed nothing on screen, and reading through the proxy still gave the old value. The docs note the other direction: “When you update properties of proxies, the original object is not mutated.” An object you push is wrapped the same way, so writing to the todo you pushed changed nothing either. Class instances get no stand-in at all. “Class instances are not proxied.” $state(new Reminder(…)) returned the same instance, and setting its plain done field left the row saying To do; declared as done = $state(false), it updated.

React puts nothing in front of your object. Its guide to updating objects in state says React “does not need to hijack their properties, always wrap them into Proxies, or do other work at initialization,” and so, “without using the state setting function, React has no idea that object has changed.” Calling the setter with the object you mutated does not help: React will “ignore your update if the next state is equal to the previous state,” as determined by Object.is. In a React 19.1.0 development mount, toggling by mutation and calling setTodos(todos) rendered the list zero times across three clicks, with or without StrictMode, and the next unrelated update showed the mutated value. Replacing the array with a mapped copy rendered it. Copying state out of a proxy is Prototype’s question.

When you have to own it

Now your calendar app gets integrations. A travel-time widget, written by a vendor or another team, renders on the event page. It needs the start time and location. It has no business with the attendees’ email addresses or your private notes, and it should never move the meeting. Hand it a stand-in: a Proxy over the event that answers reads for the fields its permissions list and refuses every write. That is this lesson’s protection proxy, with a property read as the request.

Every way of looking has to get the same answer, and each is its own trap. In Chromium 153, get and ownKeys traps hid notes from view.notes, Object.keys, JSON.stringify, and spread, and a has trap made 'notes' in view false. Without a getOwnPropertyDescriptor trap, though, asking for the descriptor returned the notes. Without traps for them, Object.defineProperty, delete, and Object.setPrototypeOf went straight through to the event. A permitted array came back as the app’s own array, so the widget could push into it. The helper below traps each of those and wraps nested values too.

Its target is an empty object, not the event, because the engine checks a proxy’s answers against its target. Over frozen state, which Immer’s produce returns, a get trap that hid a field threw “'get' on proxy: property 'notes' is a read-only and non-configurable data property on the proxy target but the proxy did not return its actual value”, and filtering ownKeys threw as well.

plugin-view.ts

// A read-only view of app state for code you did not write, such as a calendar
// integration. It reads only the fields its permissions list, and every write throws.
export type PluginView<T, K extends keyof T> = { readonly [P in K]: T[P] };

const nestedViews = new WeakMap<object, object>();

export function createPluginView<T extends object, K extends keyof T & string>(
	state: T,
	fields: readonly K[]
): PluginView<T, K> {
	const allowed = new Set<PropertyKey>(fields);
	return readOnlyView(state, (key) => allowed.has(key)) as PluginView<T, K>;
}

function readOnlyView(source: object, allowed: (key: PropertyKey) => boolean): object {
	// The target is a fresh empty object or array, never the state. With frozen state
	// as the target, a trap that hides a field breaks a Proxy invariant and throws.
	const target = Array.isArray(source) ? [] : {};
	const visible = (key: PropertyKey) => allowed(key) && Object.hasOwn(source, key);
	const refuse = (): never => {
		throw new TypeError('Integrations can read this event but not change it.');
	};
	return new Proxy(target, {
		get(target, key, receiver) {
			if (visible(key)) return wrap(Reflect.get(source, key));
			// Hidden fields read as undefined; toString and map still come from the prototype.
			return key in target ? Reflect.get(target, key, receiver) : undefined;
		},
		has: (target, key) => visible(key) || key in target,
		// Object.keys, JSON.stringify, and spread all ask these two traps.
		ownKeys: () => Reflect.ownKeys(source).filter(visible),
		getOwnPropertyDescriptor(target, key) {
			if (!visible(key)) return undefined;
			const own = Reflect.getOwnPropertyDescriptor(source, key);
			if (!own) return undefined;
			// An array target has its own non-configurable length, and the report has to
			// agree with it. Everything else is reported as configurable, as the target allows.
			const fixed = Reflect.getOwnPropertyDescriptor(target, key);
			return fixed
				? { ...fixed, value: own.value }
				: { ...own, value: wrap(own.value), configurable: true };
		},
		// Without these traps a write would land on the empty target: the state would not
		// change, the write would seem to succeed, and the next read of that field would throw.
		set: refuse,
		defineProperty: refuse,
		deleteProperty: refuse,
		setPrototypeOf: refuse,
		preventExtensions: refuse
	});
}

// An allowed field can hold an array or object. Hand out a read-only view of that
// too, the same one each time, so an integration cannot push into the app's array.
function wrap(value: unknown): unknown {
	if (typeof value !== 'object' || value === null) return value;
	let view = nestedViews.get(value);
	if (!view) {
		view = readOnlyView(value, () => true);
		nestedViews.set(value, view);
	}
	return view;
}

In Svelte the view layers over $state without losing tracking. The event prop is the parent’s state proxy, and the widget’s reads go through the view into it: in a Svelte 5.57 mount, moving the meeting updated the widget, and a $derived view followed a replaced event where a view built once kept showing the old one. Wrap the state proxy, as the docs advise: “If you need to use your own proxy handlers in a state proxy, you should wrap the object after wrapping it in $state.” Wrapped the other way, a write through the state proxy never reached the inner set trap. React treats the view as any other object, so useMemo keyed on event builds a new one for each new event; keyed on nothing, the widget kept the first event. A write during render threw to the nearest error boundary in React and to <svelte:boundary> in Svelte.

A Proxy in the page shapes an interface; it is not a security boundary. Code running in the same page can reach around it. In Chromium, a widget that replaced Reflect.get before its next read was handed the raw event, attendees and all, by the helper’s own trap. It could also read the notes from the page. For code you do not trust, run it in a sandboxed iframe and post it only the permitted fields: a frame with sandbox="allow-scripts" that read parent.document got a SecurityError. It is the rule from this section again. A check protects only what the caller cannot reach without it, and whatever the page holds, the server must still decide what reaches the page.

A todo list toggled by mutating the todo. Svelte’s $state hands you a proxy that sees the write, while a class instance it does not wrap stays on To do; React holds the object itself, and setting the same array renders nothing.

ReactAlready in your code

TodoList.tsx

import { useState } from 'react';
import { initialTodos, type Todo } from './components/todos';

export function TodoList() {
	const [todos, setTodos] = useState(initialTodos);

	function toggle(todo: Todo) {
		// State holds the object itself, with no proxy in between, so nothing
		// notices this write.
		todo.done = !todo.done;
		// The same array as the last render. Object.is finds no change, React skips
		// the render, and the row keeps saying To do. Replace instead:
		// setTodos(todos.map((t) => (t.id === todo.id ? { ...t, done: !t.done } : t)));
		setTodos(todos);
	}

	return (
		<ul>
			{todos.map((todo) => (
				<li key={todo.id}>
					<button type="button" onClick={() => toggle(todo)}>
						{todo.done ? 'Done' : 'To do'}
					</button>{' '}
					{todo.text}
				</li>
			))}
		</ul>
	);
}

07 / Recognize the family

The stand-in can do more than guard a document.

A protection proxy checks access. A caching proxy reuses a result. A remote proxy represents something reached elsewhere. A virtual proxy delays creating or loading its subject. These responsibilities can combine, and their order can change the result—as our cached launch plan demonstrates.

A reverse proxy forwards HTTP work.

Go’s httputil.ReverseProxy is an HTTP handler that forwards an incoming request to another server and sends its response back to the client. The client addresses an intermediary that reaches the origin on its behalf, with no document cache or permission policy of its own.

Read the ReverseProxy contract ↗

JavaScript also has a Proxy constructor.

JavaScript’s built-in Proxy can intercept operations such as reading or assigning a property. That mechanism lets an object stand in for a target at the language level. Our example uses ordinary methods and classes instead.

Read about JavaScript Proxy ↗

08 / Make the call

Choose the wrapper for the decision it owns.

Consider a proxy when callers should keep a stable interface while access, fetching, or representation needs a central owner. It is especially useful when a new caller should inherit those rules by receiving the same reader.

Keep a direct reader for trusted internal work when there is no access or indirection policy to centralize. For a service whose authorization already belongs in established middleware, use that boundary consistently. Adding a class is not what makes the checks complete.

Similar shapes, different reasons to introduce them
Pressure	Useful connection
Represent a resource while controlling how it is reached	Proxy: preserve the reader contract and mediate access.
Make an incompatible API fit the caller	Adapter: translate to the interface the caller needs.
Attach another responsibility around existing behavior	Decorator: compose additions through a compatible interface.
Offer a simpler entry point to several operations	Facade: organize a subsystem behind a focused surface.
Postpone setup until first demand	Lazy initialization: a timing decision a virtual proxy can use.

Proxy and Decorator can look almost identical in code, and a wrapper can serve more than one intent. Describe the actual contract: this reader stands in for the archive and decides whether the document may be returned. The name helps explain that decision; it does not replace it. One operational tie-breaker: a proxy may refuse, defer, or substitute the operation, so Bo asks for the launch plan and never receives it. A decorator always performs the operation it wraps and adds around it.

09 / Take the idea with you

Explain why “already here” still means “forbidden.”

Try it without saying “proxy”: the viewer gets a reader that checks current access before returning anything. A saved copy avoids an archive call. It never supplies permission.

Now transfer the idea. A preview becomes personalized for each workspace. Which cache key or owner must change? A teammate adds an export endpoint. Which reader should it receive? Those two changes test whether you can identify both the content boundary and the access boundary.

Connections to follow nextRelated lessons

Adapter changes how a caller speaks to something. Facade gives a workflow a smaller surface. Lazy initialization changes when setup happens. Proxy keeps the familiar request and puts a decision on its path.