1. Save the file.

2. Switch to your browser.

3. Check the result.

4. Switch back to VS Code.

5. Repeat.

Those constant window switches may seem small, but over hundreds of edits they become a real productivity drain.

With QuickServe, you can preview your project directly inside VS Code using the built-in Internal Webview, allowing you to stay focused in a single workspace.

Why use the Internal Browser?

Instead of launching your default browser every time the server starts, QuickServe can open your project inside VS Code itself.

Benefits include:

• Zero context switching between your editor and browser.

• Keep your code and preview side-by-side.

• Faster iteration while tweaking HTML and Markdown.

• Continue using Live Reload and HMR just like an external browser.

• Great for smaller screens or single-monitor setups.

For many editing tasks, you never need to leave your editor.

Think of it like having your browser embedded next to your code. Edit, save, and instantly see the result without changing applications.

How to Enable It

Open VS Code Settings and search for:

QuickServe: Open With

Change the value from:

browser

to:

internalWebview

Or edit your settings.json directly:

{
    "quickserve.openWith": "internalWebview"
}

That's it.

The next time you start QuickServe, your project opens inside VS Code instead of your default browser.

See It in Action

Requirements

The Internal Webview requires:

• VS Code v1.109 or later

• Simple Browser enabled (bundled with VS Code)

If these requirements aren't met, simply switch back to the default browser option.

When Should You Use It?

The Internal Browser is ideal for:

• Building static HTML pages

• Writing Markdown documentation

• Editing landing pages

• Following tutorials

• Rapid UI iteration

• Testing HMR without leaving the editor

If you're spending most of your time making small visual changes, this workflow keeps everything in one place.

Choosing the Right Preview Mode

QuickServe supports three preview modes:

Conclusion

Switching between applications dozens of times an hour interrupts your flow more than most developers realize.

By setting:

"quickserve.openWith": "internalWebview"

QuickServe keeps your editor and preview together, making development faster, smoother, and more focused.

Sometimes the biggest productivity improvement isn't adding new features—it's simply removing unnecessary context switches.

In the previous article, I shared how a simple curiosity about HTTPS evolved into mitm-core and the challenges I encountered while building its first architecture.

The original design achieved its goal. It successfully intercepted HTTPS traffic, supported plugins, and provided a modular, event-driven pipeline. More importantly, it helped me understand what actually happens beneath every secure web request.

But as the project evolved, so did its requirements.

Features that once felt easy to add started interacting with each other in unexpected ways. State became harder to manage, lifecycles became increasingly complex, and solving one problem often introduced another somewhere else.

At that point, I had two choices.

I could continue patching the existing architecture, or I could step back, rethink the design, and build a foundation that would support the project's future instead of limiting it.

I chose the second option.

This article isn't about new features or performance improvements. It's about the architectural decisions behind the redesign—what changed, why it changed, and how those decisions shaped the next generation of mitm-core.

Design Goals

The redesign wasn't about making the proxy faster or adding more features.

It was about building an architecture that could evolve without becoming increasingly difficult to maintain.

Before writing a single line of code, I defined a few principles that every component of the new architecture should follow.

Replace Context-Based Design with Scope-Based Design

The original architecture stored almost everything inside a single ProxyContext.

As the project grew, this became increasingly difficult to reason about because different pieces of data had completely different lifetimes.

The redesign introduced scopes instead of a single shared context.

• Session Scope — Data that lives for the lifetime of a client connection.

• Request Scope — Data created for a single request-response cycle.

• Lifecycle Scope — Temporary state that exists only while a specific pipeline phase is executing.

By separating state according to its lifetime, each component owns only the data it is responsible for.

This separation also lays a much stronger foundation for handling protocols that support multiple requests over a single connection (request multiplexing) in the future.

Make Resource Cleanup a First-Class Citizen

One of the biggest sources of bugs in the original architecture was resource management.

Sockets, streams, and requests needed deterministic cleanup.

Instead of leaving cleanup to individual handlers, the new architecture centralizes it.

Every component follows the same cleanup strategy, ensuring streams are destroyed or gracefully closed once they're no longer needed.

This dramatically reduces socket leaks, dangling resources, and connection lifecycle issues.

Make the Event System Fully Type-Safe

Events are one of the primary extension points of the framework.

The new event manager is completely statically typed, allowing the compiler to verify event names and payloads before the code ever runs.

This removes an entire class of runtime mistakes while providing much better IDE support for plugin developers.

Introduce a Real Processing Pipeline

The original execution flow gradually became a collection of handlers.

The new design formalizes it into a Chain of Responsibility with explicit Phase Orchestration.

Each phase has a well-defined responsibility, executes in a predictable order, and remains independent from the others.

This makes the request lifecycle significantly easier to understand and extend.

Centralize Request State

Instead of every component maintaining its own temporary state, request-specific information is stored in a centralized state store.

This gives every phase controlled access to shared request data without tightly coupling different parts of the system.

Optimize Expensive Operations

Some operations—such as generating leaf certificates—are computationally expensive.

The redesigned architecture moves certificate generation into worker threads and introduces a layered caching strategy that combines in-memory caching with persistent filesystem storage.

The goal is simple: generate certificates only when necessary and reuse them whenever possible.

Build Reusable Infrastructure

Rather than solving isolated problems, the redesign introduces reusable infrastructure that can support future capabilities.

This includes components such as:

• A centralized response cache.

• A configurable rule manager.

• A dedicated plugin manager.

• Shared state management.

• A transport layer responsible for moving data through the proxy.

Each of these systems exists independently of the request pipeline, making the overall architecture more modular and easier to extend.

These goals became the blueprint for the new architecture. Every major design decision that follows can be traced back to one or more of these principles.

The Biggest Architectural Change

The redesign wasn't about introducing new components.

It was about changing how I thought about the proxy itself.

In the original architecture, the connection was the center of everything. Most of the state, lifecycle, and processing revolved around a single context object that was passed through the pipeline.

The more features I added, the more responsibilities that object accumulated.

During the redesign, I asked myself a simple question:

What is the actual unit of work inside a proxy?

The answer wasn't "a connection."

A single connection contains multiple kinds of state, each with a completely different lifetime and responsibility.

Some data exists as long as the client stays connected.

Some exists only for a single request.

Some only exists while a particular pipeline phase is executing.

Trying to represent all of these with a single context object inevitably mixed responsibilities together.

The new architecture separates the proxy into independent scopes.

• Session Scope manages everything related to the lifetime of a client connection.

• Request Scope owns everything required for a single request-response cycle.

• Lifecycle Scope stores temporary state that exists only while a pipeline phase is executing.

Each scope has a clear owner, a clear lifetime, and a well-defined responsibility.

Instead of one object trying to represent everything, each layer now manages only the state it truly owns.

This change affected almost every part of the framework.

The pipeline became simpler.

Plugins became easier to reason about.

Cleanup became deterministic.

State propagation became explicit instead of implicit.

Most importantly, the architecture now reflects how the proxy actually behaves rather than forcing every piece of data into the same abstraction.

The complete architecture now looks like this:

After introducing scope-based state management, the remaining pieces naturally fell into place. The transport layer became centralized, the pipeline evolved into a proper phase orchestrator, resource management became predictable, and every subsystem gained a much clearer responsibility.

This wasn't just a refactor.

It was a shift from building features around an architecture to building an architecture that naturally supports new features.

Separating State by Lifetime

The core idea behind the redesign was surprisingly simple:

Not all data lives for the same amount of time, so it shouldn't live in the same object.

In the original architecture, almost every piece of information eventually found its way into a single context object. Connection details, request metadata, temporary pipeline state, routing information, and plugin data all coexisted in the same place.

This worked initially, but over time the boundaries between different responsibilities became unclear.

The redesign separates state according to its natural lifetime.

Session Context

A Session Context is created when a client establishes a connection with the proxy.

It contains information that remains valid throughout the lifetime of that connection, regardless of how many requests are processed.

Examples include:

• Connection identifiers

• Underlying socket

• Negotiated protocol

• Connection-level errors

• Custom TLS certificates

Once the client disconnects, the session context is destroyed.

Request Context

Every incoming request creates its own Request Context.

Unlike the session context, this object exists only for the lifetime of a single request-response transaction.

It contains everything related to that request, including:

• Client request and response objects

• Upstream request and response objects

• Headers

• Request and response bodies

• Routing information

• Status information

Once the response has been sent back to the client, the request context is no longer needed.

This separation means multiple requests can safely exist within the same client session without interfering with one another.

Request Lifecycle

Some information doesn't belong to either the connection or the request.

Instead, it only exists while the proxy is actively processing a request through the pipeline.

For this, I introduced the Request Lifecycle.

Rather than storing operational state inside the request itself, the lifecycle tracks information such as:

• Current execution state

• Phase transitions

• Request hijacking

• Timing metrics

• Performance measurements

This keeps execution state separate from business data while giving the pipeline complete control over how a request progresses.

Why This Matters

Separating state by lifetime solved several problems at once.

Responsibilities became much clearer because each context owned only the data relevant to its lifetime.

Cleanup also became far more predictable. When a request finishes, its request context and lifecycle can be discarded without affecting the surrounding session. Likewise, when a connection closes, the entire session context can be released safely.

Perhaps the biggest benefit, however, is that the architecture now mirrors how the proxy actually operates. Instead of forcing every piece of information into a single object, each layer has a clear owner, a clear purpose, and a well-defined lifecycle.

This separation became the foundation upon which the rest of the architecture was built.

Centralized Transport Layer

One of the biggest responsibilities of a proxy is moving data between two endpoints.

In the original architecture, each handler was responsible for creating or managing its own network connections. For example, the request handler initiated the upstream request, the handshake handler dealt with decrypted streams, and the response handler handled sending data back to the client.

While this worked, it also meant that transport logic was scattered throughout the pipeline.

The redesign introduces a dedicated Transport Layer whose sole responsibility is moving data between the client and the upstream server.

Instead of handlers creating sockets or managing streams directly, they simply delegate those responsibilities to the transport layer.

The transport layer is divided into three distinct responsibilities:

• Inbound — Receives and prepares incoming client traffic after the handshake phase.

• Upstream Initiator — Establishes and manages communication with the destination server when instructed by the request handler.

• Outbound — Returns the processed upstream response back to the client.

This separation keeps networking concerns isolated from request processing.

Handlers now focus on what should happen, while the transport layer is responsible for how data moves through the proxy.

The result is a cleaner architecture with well-defined responsibilities, easier testing, and a single place to evolve transport-related behavior without affecting the rest of the pipeline.

Pipeline Evolution

One of the more subtle problems in the original architecture was pipeline ownership.

Although the proxy had clearly defined phases, there wasn't a single component responsible for orchestrating them.

Instead, each handler decided what should happen next by invoking the pipeline again. In other words, handlers weren't just processing their own phase—they were also responsible for deciding how execution continued.

This made the control flow harder to follow because the pipeline was effectively orchestrating itself.

The redesign establishes a much stricter boundary.

The Middleware becomes the single entry point into the execution pipeline.

Once Pipeline.run() begins, it becomes the sole owner of execution.

Each handler is responsible for only one thing:

• Execute its own phase.

• Update the lifecycle if another phase should follow.

• Return control to the pipeline.

The pipeline then decides what happens next.

Instead of handlers recursively invoking the next stage, the pipeline continuously evaluates the current lifecycle state and orchestrates phase execution until the request completes or is intentionally terminated.

This seemingly small change has several advantages:

• Handlers no longer control execution flow.

• Pipeline orchestration exists in one place.

• Phase transitions become predictable and easy to debug.

• Aborting or hijacking a request becomes a first-class operation rather than a special case.

• Error handling is centralized instead of duplicated across handlers.

By separating execution from orchestration, handlers became significantly smaller and easier to reason about, while the pipeline evolved into a true execution engine rather than just a collection of sequential function calls.

Resource Management & Cleanup

One lesson I learned while building the first version of the proxy was that processing requests is only half the job.

The other half is cleaning everything up correctly.

A proxy sits between two endpoints and constantly manages sockets, streams, requests, and responses. If even one of these resources isn't released properly, problems begin to accumulate over time—dangling streams, half-open connections, memory growth, and difficult-to-debug networking issues.

In the original architecture, cleanup was largely the responsibility of individual handlers. Each handler had to remember which resources it created and when they should be released. This worked for simple cases, but it also meant cleanup logic became scattered throughout the codebase.

The redesign centralizes resource management into a dedicated cleanup utility.

Rather than each component implementing its own shutdown logic, handlers simply hand over the resources they own, and the cleanup layer safely closes or destroys them when their lifecycle ends.

ProxyUtils.cleanUp([
  clientSocket,
  upstreamSocket,
  requestStream,
  responseStream,
]);

This approach provides several advantages:

• A single, consistent strategy for releasing resources.

• Less duplicated cleanup code across handlers.

• Deterministic destruction of streams and sockets.

• Reduced risk of dangling connections and resource leaks.

• Simpler handlers that focus on request processing rather than lifecycle management.

Most importantly, cleanup is now treated as part of the architecture instead of an implementation detail.

Every resource has a well-defined owner, and every owner has a clear responsibility for releasing it when its work is complete. That makes the entire request lifecycle more predictable and the proxy far more stable during long-running workloads.

Centralized State Store

As the proxy grew, different components needed a way to share operational state during a request's lifetime.

Rather than scattering temporary flags across multiple objects, the redesign introduces a centralized state store bound to each request lifecycle.

It provides a single location for tracking execution state, such as cache hits, completion status, and error conditions, while also allowing plugins and middleware to attach custom request-specific data.

The state store combines strongly typed built-in state with flexible custom entries, offering compile-time safety for core framework properties without restricting extensibility.

This gives every phase of the pipeline a consistent way to exchange information without tightly coupling components or polluting the request and session contexts.

Strongly Typed Event System

Events are one of the primary extension points in mitm-core, allowing plugins and internal components to react to different stages of the proxy lifecycle.

In the original architecture, the event system relied on loosely typed event names and payloads. While functional, it left room for runtime mistakes such as misspelled event names or incorrect payload structures.

The redesigned event manager is fully statically typed. Every event has a well-defined payload, allowing TypeScript to validate both event names and their associated data at compile time.

Beyond improving developer experience through better autocompletion and type inference, this approach eliminates an entire class of runtime errors and makes plugin development significantly safer.

As the framework continues to grow, the event system remains both extensible and reliable without sacrificing type safety.

Performance Optimizations

As the architecture matured, performance became just as important as correctness. Rather than optimizing prematurely, I focused on the parts of the proxy that were genuinely expensive or frequently repeated.

Worker-thread certificate generation

Generating leaf certificates is one of the most computationally expensive operations in a MITM proxy. Performing this work on the main event loop would introduce unnecessary latency and reduce the proxy's ability to handle concurrent requests.

To avoid blocking the event loop, certificate generation is delegated to a pool of worker threads using Piscina. This allows expensive cryptographic operations to run in parallel while the main thread remains responsive.

Multi-layer certificate cache (LRU + filesystem)

Even with worker threads, generating a certificate for every connection would be wasteful.

To eliminate redundant work, the proxy uses a two-level caching strategy:

• In-memory LRU cache for frequently accessed certificates.

• Filesystem cache for long-term persistence across proxy restarts.

This layered approach significantly reduces certificate generation overhead while maintaining fast lookup times for commonly requested domains.

Response cache

The redesigned architecture also introduces a dedicated response cache.

Rather than always forwarding identical requests to the upstream server, cacheable responses can be reused when appropriate, reducing network traffic and improving response times.

By treating caching as a dedicated subsystem instead of embedding it within request handlers, the proxy keeps its execution pipeline clean while making cache behavior easier to configure and extend.

Together, these optimizations reduce unnecessary computation, minimize repeated work, and keep the proxy responsive under sustained workloads without complicating the overall architecture.

Built for Extensibility

A proxy framework shouldn't require modifying its core every time new behavior is needed. One of the primary goals of the redesign was to make mitm-core extensible through dedicated infrastructure rather than hardcoded logic.

Two key components enable this: the Rule Manager and the Plugin Manager.

Rule Manager

Many proxy features depend on configurable rules—whether it's bypassing specific domains, blocking requests, or applying custom routing behavior.

The redesigned Rule Manager provides a generic framework for defining and managing these rule sets. Each rule engine owns its own parser and storage while sharing the same underlying infrastructure.

Rule files are automatically created if they don't exist, watched for changes, and reloaded using a debounced mechanism whenever they're modified. This allows configuration changes to take effect without restarting the proxy.

Because parsing logic is abstracted behind a simple interface, different rule formats can be implemented without changing the framework itself.

Plugin Manager

The Plugin Manager provides the primary extension mechanism for the framework.

Plugins subscribe to well-defined lifecycle events and receive strongly typed payloads corresponding to each stage of proxy execution. Rather than modifying the framework's internal components, developers can extend behavior by implementing small, focused plugins that react to specific events.

This event-driven model keeps the core architecture isolated while allowing new functionality—such as logging, monitoring, authentication, request inspection, or custom routing—to be added independently.

Together, the Rule Manager and Plugin Manager make mitm-core easier to customize without increasing coupling inside the framework. New behavior can be introduced by composing reusable components instead of modifying existing ones, keeping the architecture both flexible and maintainable as it grows.

Conclusion

Redesigning mitm-core wasn't about adding more features—it was about building a stronger foundation.

By separating state according to its lifetime, centralizing transport and resource management, formalizing pipeline orchestration, and introducing reusable infrastructure, the framework became significantly easier to understand, extend, and maintain.

Every architectural decision in this redesign was driven by the same principle: make the system reflect how a proxy actually works. The result is an architecture that is not only cleaner internally but also better prepared for future capabilities.

What's Next

While this redesign establishes a solid foundation, there is still plenty of work ahead.

The next major milestone is expanding the proxy's protocol support, beginning with:

• HTTP/2 interception, enabling inspection and modification of modern multiplexed HTTP traffic.

• WebSocket interception, allowing real-time bidirectional communication to be observed and manipulated through the same extensible pipeline.

With the core architecture now in place, these capabilities can be introduced as natural extensions of the framework rather than requiring another fundamental redesign.

Introduction

I didn't start mitm-core with the goal of building another proxy framework.

In fact I had a much simpler question:

How does an HTTPS request actually work under the hood?

Every day we type a URL into a browser, and within miliseconds a secure connection is established. We know the high-level concepts — TLS, certificates, encryption — but what really happens between clicking Enter and seeing a webpage?

I wanted to understand every step of that journey.

So I decided to build a simple MITM (Man-in-the-Middle) proxy from scratch. The idea wasn't to create a production-ready tool or compete with existing projects. It was purely an experiment—a way to learn by rebuilding the entire flow myself.

I expected to forward a few requests, generate some certificates, and call it a day.

I was completely wrong.

Every answer uncovered two more questions. A simple HTTP proxy became HTTPS interception. HTTPS interception led to certificate generation. Certificate generation led to TLS handshakes. Then came HTTP/2, ALPN negotiation, streaming, connection lifecycles, caching, plugins, and countless edge cases that browsers handle every second without us ever noticing.

What started as a weekend experiment gradually evolved into mitm-core—a modular, extensible MITM framework that taught me far more about networking than I ever expected.

In this article, I'll share that journey, the mistakes I made, the problems I encountered, and why they eventually led me to redesign the entire architecture from the ground up.

What is a MITM Proxy?

Imagine you send a letter to your friend.

Normally, the journey looks like this:

You ─────────────► Friend

Now imagine there's someone sitting in the middle.

Instead of sending the letter directly, it goes through them first.

You ─────► Middle Person ─────► Friend

The middle person can:

• Read the letter

• Modify its contents

• Block it entirely

• Or simply forward it without making any changes

A Man-in-the-Middle (MITM) Proxy works in exactly the same way—but instead of letters, it sits between a client (such as your browser) and a server, intercepting network traffic.

Browser ─────► MITM Proxy ─────► Website

From the browser's perspective, it's communicating directly with the website.

From the website's perspective, it's communicating directly with the browser.

The proxy quietly sits in the middle, forwarding data between both sides while having complete visibility into the communication.

This makes MITM proxies incredibly useful for tasks such as:

• Debugging HTTP requests and responses

• Inspecting API traffic

• Security testing

• Performance analysis

• Building developer tools

Of course, intercepting encrypted HTTPS traffic isn't as straightforward as plain HTTP. Modern browsers expect to communicate securely with the server, so the proxy has to convince both sides that it's the legitimate endpoint.

That's where things start getting interesting—and much more complicated.

The rabbit hole

At first, the plan seemed simple.

I thought I'd create a proxy that accepted an HTTP request, forwarded it to the destination server, received the response, and sent it back to the client.

Simple enough.

That illusion lasted only a few hours.

The moment I moved from HTTP to HTTPS, I discovered that I wasn't just forwarding requests anymore—I was participating in the entire communication process.

To inspect encrypted traffic, the proxy first has to establish a secure connection with the client. At the same time, it also needs another secure connection with the actual server. Somehow, it has to sit between both without either side realizing they're not talking directly to each other.

That was only the beginning.

One solved problem immediately revealed another:

• How do browsers decide whether to trust a certificate?

• How are certificates generated on the fly for every domain?

• What exactly happens during a TLS handshake?

• How does the CONNECT method establish an HTTPS tunnel?

• How does a proxy decrypt HTTPS traffic without the browser complaining?

• How should requests and connections be managed throughout their lifecycle?

• How can plugins intercept traffic without breaking the flow?

• How do you handle errors, caching, and resource cleanup correctly?

Every answer uncovered another layer of the networking stack.

What I initially thought was a single protocol turned out to be an ecosystem of protocols, handshakes, streams, state machines, and edge cases—all working together to make something as simple as loading a webpage feel instantaneous.

By this point, the project had stopped being "just a proxy."

It had become a deep dive into how modern web communication actually works. And before I realized it, I was no longer just learning HTTPS—I was designing the architecture needed to support it.

Designing the first architecture

By this point, it was obvious that a simple "receive a request and forward it" approach wasn't going to scale.

Every connection had to go through multiple stages. A raw TCP connection wasn't the same as an HTTPS handshake, and an incoming request shouldn't be handled the same way as an outgoing response.

Instead of putting everything inside one giant function, I decided to split the proxy into a series of well-defined phases.

The idea was simple: each phase would have a single responsibility and execute in a predictable order.

Each handler was responsible for only one stage of the connection lifecycle.

• TCP Handler accepted and prepared new connections.

• Handshake Handler established secure communication for HTTPS traffic.

• Request Handler processed incoming requests before forwarding them upstream.

• Response Handler intercepted the upstream response before sending it back to the client.

To keep the system extensible, the entire pipeline was driven by events. Plugins could subscribe to different stages without modifying the core implementation. This separation made the codebase easier to reason about and allowed new functionality to be added with minimal changes to the existing flow.

At the time, this architecture felt like the right balance between simplicity and flexibility. It was modular, easy to extend, and much cleaner than a monolithic request handler.

It also laid the foundation for everything that came next—even though, as I would later discover, it had limitations that only became visible as the project grew.

The engineering problems

The first architecture worked.

It accepted connections, decrypted HTTPS traffic, forwarded requests, intercepted responses, and allowed plugins to hook into different stages of the lifecycle.

But as the project grew, the cracks started to appear.

Most of these weren't bugs—they were architectural limitations that became obvious only after adding more features.

• One Context for Everything

The biggest issue was that everything lived inside a single ProxyContext.

Connection state, request state, certificates, routing information, temporary variables, plugin data—everything shared the same object.

Initially, this felt convenient.

Over time, it became increasingly difficult to determine which data belonged to the connection, which belonged to a single request, and which was only needed for a specific stage of the pipeline.

Plugins frequently mutated the same object, making state propagation harder to reason about and increasing coupling between different parts of the system.

• Lifecycle Management Became Messy

As more features were added, managing the lifecycle of sockets and requests became increasingly complex.

There wasn't a clear separation between connection setup, request processing, response handling, and cleanup.

That led to several issues I spent a considerable amount of time debugging:

• Sockets remaining open longer than expected.

• CLOSE_WAIT connections caused by sockets not being cleaned up properly.

• Premature socket termination.

• Exceptions such as:

Error: Can't write to socket after response has been sent

None of these problems were particularly difficult on their own, but together they made the codebase harder to maintain.

• The Event System Didn't Scale

The project relied heavily on events, but the original event manager wasn't statically typed.

As the number of events increased, it became easier to subscribe to incorrect event names, pass invalid payloads, or accidentally introduce inconsistencies that TypeScript couldn't detect.

The implementation also made listener management more difficult than it needed to be, increasing the risk of lingering listeners and unnecessary memory usage.

• Resource Management

Network programming is fundamentally about managing resources.

Every accepted connection creates sockets.

Every HTTPS request introduces additional streams and state.

Every missed cleanup eventually consumes memory.

I learned this lesson the hard way.

A small oversight in socket cleanup could leave connections stuck in CLOSE_WAIT, gradually increasing resource usage until the proxy became unstable.

These weren't problems that could be solved with another try...catch block or a few extra conditionals.

They pointed to something deeper.

The architecture itself had reached a point where adding new functionality was becoming harder than it should have been.

And that's when I started asking a different question:

Instead of fixing individual problems, what if I redesigned the architecture so these problems became much harder to create in the first place?

The realization

After fixing countless bugs, refactoring handlers, and improving different parts of the proxy, I noticed something interesting.

Most of the problems weren't caused by the individual components.

The certificate generation worked.

The request forwarding worked.

The plugin system worked.

The handlers worked.

Yet every new feature seemed to make the project a little harder to reason about.

I found myself spending more time managing interactions between components than actually building new functionality.

That was the moment I realized I was solving symptoms rather than the underlying problem.

The architecture that had helped me get the project off the ground was now limiting its growth.

Instead of asking,

"How do I fix this bug?"

I started asking,

"Why is this bug possible in the first place?"

That single question changed how I looked at the project.

Rather than continuing to patch the existing design, I decided to rethink the architecture from first principles.

If different kinds of state had different lifetimes, they shouldn't live in the same object.

If every stage had its own responsibility, it should also have its own lifecycle.

If resources needed explicit cleanup, the architecture should make cleanup a natural part of execution—not an afterthought.

That decision marked the end of the first generation of mitm-core.

The next version wasn't about adding more features.

It was about building a stronger foundation that would make future features easier to implement, easier to maintain, and far less error-prone.

In the next article, I'll walk through that redesign and explain how the new architecture emerged from these lessons.

QuickServe has a built-in Self-Healing Mode that handles certificate generation for you. You just need to tweak your settings.json.

Here is the exact setup.

The Baseline Configuration

Navigate to Settings > Extensions > User/Workspace > QuickServe Configuration (or just open your settings.json).

You'll be targeting this JSON block:

"quickserve.https": {
    "enable": true,
    "certPath": "",
    "keyPath": ""
}

By setting "enable": true and leaving the paths empty, QuickServe takes over. What happens next depends on what is installed on your machine.

Method 1: The Self-Healing Fallback (With Browser Warning)

If you don't have any local Certificate Authority tools installed, do absolutely nothing else.

With the empty paths above, QuickServe's Self-Healing Mode kicks in. It automatically generates a standard self-signed certificate in the background to serve your project over HTTPS.

Result: Your browser will throw an ERR_CERT_AUTHORITY_INVALID warning because it's self-signed. Just click Advanced > Proceed to localhost to bypass it, and you're good for quick testing.

Method 2: Trusted Local CA (No Browser Warning)

Use mkcert to create a local Certificate Authority. This permanently prevents browser warnings and avoids strict cross-origin blocks.

1. Install mkcert:

# macOS
brew install mkcert

# Windows (using Chocolatey)
choco install mkcert

# Linux (Ubuntu/Debian)
sudo apt install libnss3-tools mkcert

2. Setup the local CA (Run once per machine):

mkcert -install

3. Let QuickServe Take Over:

With mkcert installed and the certPath/keyPath still empty in your settings.json, simply restart the QuickServe extension. The Self-Healing Mode will detect mkcert and automatically generate a fully trusted local certificate for you.

Result: A smooth, trusted https://127.0.0.1 connection. No red text, no warnings.

Bonus: The Manual Override

If you already have your own custom OpenSSL certificates and want to bypass the Self-Healing Mode entirely, just provide the absolute paths in your settings.json:

JSON

"quickserve.https": {
    "enable": true,
    "certPath": "/absolute/path/to/cert.pem",
    "keyPath": "/absolute/path/to/key.pem"
}

Save the file, restart the extension, and QuickServe will use your specific files.