Introduce HttpServer (and begin deprecating HttpPlugin) #433

heyitsaamir · 2026-01-16T06:58:18Z

In this PR, we introduce a new object called HttpServer and begin to deprecate HttpPlugin.

Main changes

Create HttpServer internal class. It accepts an IHttpAdapter which is the server implementation.
Pulled out the express implementation as an IHttpAdapter
Deprecated HttpPlugin, and made it use HttpServer + ExpressAdapter.
Changed BotBuilder/A2A/Mcp plugins to depend on HttpServer vs. HttpPlugin.
Added examples to show how powerful IHttpAdapter can be with different types of servers (hono, fastify).
Minor refactor of the jwt middleware such that we can reuse it in HttpServer and app.embed.

Why:

HTTP is a core part of our sdk. Our App object uses HTTP to set up a server, perform auth validations, and pipe the request to the handlers that are attached, and then return the response. Key part is that Http is a core part of App, not a plugin, since core functionality is dependent on it.
Even inside the App object, we were doing special casing for this Http"Plugin" whereas it should never have really been a plugin to begin with. By making it a plugin, we were exposing many non-plugin essential things to the plugin system in general.

So what should it have been? Well, HTTP Plugin had these responsibilities

Set up the express server
Perform validations if credentials were present
Pass the incoming request to App
Once App handlers have had a chance to process this incoming request, pass the response back to the server.

So, we introduce a new object called HttpServer whose responsibilities are essentially that ^. This object is not a plugin, but an object that's created by App itself.

Customization

Now this idealogical shift doesn't really warrant us doing this refactor, but we started seeing requests from folks who wanted to hook Teams functionality into existing servers, or replace the underlying server infra with a non-express server. Our recommendation was to rebuild a new HttpPlugin. But rebuilding this plugin is not simple (since we don't really document it anywhere, and didn't expect folks to build their own).
So HttpServer exposes an HttpAdapter concept. To build the adapter, one simply needs to build out a handler for extracting request data, and a handler for responses. This means that you can build simple custom adapters for your own existing servers. (And if you don't pass one in, we'll build a default express one.) Examples of servers are in the http-adapters folder under examples/.

Backward Compat

We've updated HttpPlugin to basically use HttpServer with an ExpressAdapter internally for backward compat. I don't think this should lead to any breaking changes (even if someone passes in their own HttpPlugin). (Tested BotBuilderPlugin, from examples, and it worked without any changes).
However, it should be noted that I marked HttpPlugin as deprecated in this PR, so it should be discouraged going forward, and after the next few versions, it'll be removed.

Testing

I tested by running the following examples:

Echo bot
Devtools
BotBuilder
HttpPlugin
Tabs
AI (streaming and regular completions)

skip-test-verification (added manifest for tabs)

PR Dependency Tree

PR Simplify HTTP Plugin architecture #424
- PR Introduce HttpServer (and begin deprecating HttpPlugin) #433 👈
  - PR Upgrade to express v5 #442

This tree was auto-generated by Charcoal

examples/http-adapters/README.md

packages/apps/src/http/http-server.ts

examples/http-adapters/package.json

rido-min · 2026-01-22T16:35:59Z

examples/http-adapters/express/teams-app.ts

+});
+
+expressApp.get('/', (req, res) => {
+  res.send(`


this is cute, should we do the same in other languages/samples?

heyitsaamir

Questions:

Should we remove app.initialize()? I feel like we could remove it, but i like having it because it could give us a way to initialize things asynchronously if needed.
Ideally we should not be shipping with a server at all -- If we want to do serve(new App()) where serve comes from an express specific package, that'll lead to a pretty big breaking change for all our docs for our simplest use-cases. For this reason, I think we should leave app.start the way it is, and for v3 consider removing .start.

heyitsaamir · 2026-01-24T00:33:28Z

packages/apps/src/app.ts

      }
    }

+    // initialize server


We could technically move this to the constructor, as with above ^. So then we won't need app.initialize() anymore.

heyitsaamir · 2026-01-24T00:45:41Z

external/a2a/src/server/plugin.ts


-  @Dependency()
-  protected readonly _httpPlugin!: HttpPlugin;
+  @HttpServer()


For these plugins, we are exposing the HttpServer because of backward compat. The A2A Plugin does a check to see if the adapter is Express or not since it was built with an express server in mind.

heyitsaamir · 2026-01-24T00:45:51Z

external/mcp/src/plugin.ts


-  @Dependency()
-  readonly httpPlugin!: HttpPlugin;
+  @HttpServer()


For these plugins, we are exposing the HttpServer because of backward compat. The MCP Plugin does a check to see if the adapter is Express or not since it was built with an express server in mind.

heyitsaamir · 2026-01-24T00:48:13Z

packages/apps/src/http/express-adapter.ts

+ * - Request/response data extraction and sending
+ * - Server lifecycle management
+ */
+export class ExpressAdapter implements IHttpAdapter {


This adapter does a lot, but that's mainly because we are maintaining some of the exposed functions from HttpPlugin.

heyitsaamir · 2026-01-24T01:00:12Z

packages/apps/src/http/express-adapter.ts

+ * - Request/response data extraction and sending
+ * - Server lifecycle management
+ */
+export class ExpressAdapter implements IHttpAdapter {


This implementation is the "Default" one we ship with. Ideally we should not be shipping with a server at all -- If we want to do serve(new App()) where serve comes from an express specific package, that'll lead to a pretty big breaking change for all our docs for our simplest use-cases. For this reason, I think we should leave app.start the way it is, and for v3 consider removing .start.

heyitsaamir · 2026-01-24T01:02:49Z

packages/apps/src/http/http-server.ts

+        }
+
+        try {
+          token = await this.validateJwt(authHeader, body);


This isn't using the middleware approach to validate tokens. Just doing it inline. I think that's okay, but if anyone thinks differently, lmk.

heyitsaamir · 2026-01-24T01:03:40Z

packages/apps/src/plugins/http/plugin.ts

  name: 'http',
  version: pkg.version,
-  description: 'the default plugin for receiving activities via HTTP',
+  description: 'Will be deprecated: Use HttpServer with server option instead',


Specifies that this is scheduled for deprecation.

heyitsaamir · 2026-01-24T01:04:07Z

packages/apps/src/plugins/http/plugin.ts

+    this.expressAdapter = new ExpressAdapter(server);
+    this._server = new HttpServer(this.expressAdapter, options);


Uses ExpressAdapter internally, since that was the behavior from before

The previous architecture tightly coupled HTTP transport concerns with activity sending logic: **Previous Architecture:** ``` HttpPlugin (transport) → implements ISender (sending) → has send() method (creates new Client per call) → has createStream() method → knows about Activity protocol details ActivityContext → depends on ISender plugin → cannot work without transport plugin → conflates transport and sending concerns ``` Key Issues: - HttpPlugin created NEW Client instances on every send() call - Transport plugins (HttpPlugin) were forced to implement send/createStream - Users couldn't "bring their own server" without implementing ISender - ActivityContext was tightly coupled to plugin architecture - HttpPlugin knew about Bot Framework Activity protocol details ``` HttpPlugin (transport) → only handles HTTP server/routing/auth → emits ICoreActivity (minimal protocol knowledge) → just passes body payload to app ActivitySender (NEW) → dedicated class for sending activities → receives injected, reusable Client → handles all send/stream logic → private to App class ActivityContext → uses send callback (abstraction) → receives pre-created stream → no direct dependency on ActivitySender ``` - Centralized all activity sending logic - Receives reusable Client in constructor (no per-send instantiation) - Private to App class - internal implementation detail - Provides send() and createStream() methods - Minimal fields transport layer needs: serviceUrl, id, type - Extensible via [key: string]: any for protocol-specific fields - Transport plugins work with this instead of full Activity type - Parsing to Activity happens in app.process.ts - No longer needed - plugins don't send activities - Plugins only handle transport (receiving requests) - Breaking change, but simplifies plugin architecture - Constructor accepts send callback function - Receives pre-created stream (not factory function) - No knowledge of ActivitySender implementation - Proper abstraction via dependency injection - Initially renamed to ActivityStream - Reverted because it's still HTTP-specific (uses Bot Framework HTTP Client API) - Moved from src/plugins/http/stream.ts to src/http-stream.ts - Still transport-specific, just not plugin-owned 1. **ISender removed** - Custom plugins should implement IPlugin only 2. **IActivityEvent changed** - Now has body: ICoreActivity instead of activity: Activity 3. **Plugin.onActivity** - Still receives parsed activity: Activity (unchanged) 4. **App.process signature** - Internal change, not exposed to plugin API Before: ```typescript class MyPlugin implements ISender { send(activity, ref) { ... } // Required createStream(ref) { ... } // Required async onRequest(req, res) { const activity: Activity = req.body; // Need Activity type await this.$onActivity({ activity, token }); } } ``` After: ```typescript class MyPlugin implements IPlugin { // No send() or createStream() needed! async onRequest(req, res) { // Just pass body - don't need Activity type knowledge await this.$onActivity({ body: req.body, // ICoreActivity (minimal fields) token }); } } ``` 1. **Client Reuse** - ActivitySender reuses same Client, no per-send instantiation 2. **Separation of Concerns** - Transport vs sending clearly separated 3. **Bring Your Own Server** - Easy to implement custom transports (Socket.io, gRPC, etc.) 4. **Less Protocol Knowledge** - Transport layer only needs ICoreActivity, not full Activity 5. **Cleaner Architecture** - Each class has single responsibility 6. **Better Abstraction** - ActivityContext uses callbacks, not direct dependencies - src/activity-sender.ts - Dedicated activity sending class - src/http-stream.ts - Moved from src/plugins/http/stream.ts - src/app.ts - Added activitySender, updated send() - src/app.process.ts - Removed sender param, uses activitySender - src/plugins/http/plugin.ts - Removed send/createStream, works with ICoreActivity - src/contexts/activity.ts - Uses callbacks instead of ISender plugin - src/events/activity.ts - Added ICoreActivity, changed to body field - src/types/plugin/sender.ts - Removed ISender, kept IActivitySender - src/plugins/http/stream.ts - Moved to src/http-stream.ts - ISender interface - Completely removed

heyitsaamir mentioned this pull request Jan 16, 2026

Simplify HTTP Plugin architecture #424

Open

heyitsaamir force-pushed the aamirj/simlifyHttp branch from f07e077 to d9a529e Compare January 16, 2026 07:09

heyitsaamir force-pushed the httpAdapter branch 3 times, most recently from 6601a42 to 7e55c15 Compare January 17, 2026 07:13

heyitsaamir changed the title ~~Introduce Configurable Http Plugin~~ Introduce HttpServer (and begin deprecating HttpPlugin) Jan 20, 2026

lilyydu reviewed Jan 21, 2026

View reviewed changes

examples/http-adapters/README.md Outdated Show resolved Hide resolved

examples/http-adapters/README.md Outdated Show resolved Hide resolved

heyitsaamir commented Jan 22, 2026

View reviewed changes

packages/apps/src/http/http-server.ts Outdated Show resolved Hide resolved

rido-min reviewed Jan 22, 2026

View reviewed changes

examples/http-adapters/package.json Outdated Show resolved Hide resolved

rido-min reviewed Jan 22, 2026

View reviewed changes

heyitsaamir force-pushed the aamirj/simlifyHttp branch from 2fa2032 to 4590e50 Compare January 23, 2026 18:55

heyitsaamir force-pushed the httpAdapter branch 5 times, most recently from 4c1ca04 to 5422e29 Compare January 24, 2026 09:20

heyitsaamir commented Jan 24, 2026

View reviewed changes

heyitsaamir mentioned this pull request Jan 24, 2026

Upgrade to express v5 #442

Open

heyitsaamir force-pushed the httpAdapter branch 2 times, most recently from 30af118 to 4ec6679 Compare January 26, 2026 16:31

heyitsaamir added 10 commits January 26, 2026 09:04

Configurable Http Plugin

3e6af08

Fix lint

8ab16d1

Remove configurable-http-plugin for HttpServer.

4f53f18

Use Adapter

660e392

Fix

38972de

Jwt Validation

f5230f5

HttpServer

b57ffe8

Logger

7acbcbc

Fix

ff52956

Fix tests

fee1672

heyitsaamir added 23 commits January 26, 2026 09:04

Update

235c202

Revert

15855e3

Revert

d6582a9

Configurable Http Plugin

6795d82

Fix lint

65d71ab

Remove configurable-http-plugin for HttpServer.

8555f2b

Use Adapter

638f876

HttpServer

3d2ec46

Remove paths

38c274f

Fix examples

9ada3a0

Fix readme

df71c55

Fix

a4c63e2

package-lock.json

fec351f

nextjs -> fastify

0f2c0df

fix ci

6df7ce3

fix bot builder

8556c4a

Fix tests

42c7614

Fix

df6cf81

Add build essential

1d3651b

Revert express

e6e08a0

add test for tab

b5139d0

fix tests

95d91e9

heyitsaamir force-pushed the httpAdapter branch from 4ec6679 to 95d91e9 Compare January 26, 2026 17:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce HttpServer (and begin deprecating HttpPlugin) #433

Introduce HttpServer (and begin deprecating HttpPlugin) #433

Uh oh!

heyitsaamir commented Jan 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rido-min Jan 22, 2026

Uh oh!

heyitsaamir left a comment

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

heyitsaamir Jan 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		this.expressAdapter = new ExpressAdapter(server);
		this._server = new HttpServer(this.expressAdapter, options);

Introduce HttpServer (and begin deprecating HttpPlugin) #433

Are you sure you want to change the base?

Introduce HttpServer (and begin deprecating HttpPlugin) #433

Uh oh!

Conversation

heyitsaamir commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Main changes

Why:

Customization

Backward Compat

Testing

PR Dependency Tree

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

heyitsaamir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

heyitsaamir commented Jan 16, 2026 •

edited

Loading