Fix ExpressAdapter to accept Express app directly (#504)

## Summary
- **Fix `ERR_HTTP_HEADERS_SENT`** when passing an `http.Server` that
already has an Express app attached — the adapter no longer creates a
second Express app in that scenario
- `ExpressAdapter` constructor now accepts `http.Server |
express.Application | undefined`:
- **Express app passed**: uses it directly - assumes the http server is
being managed by the user directly.
- **http.Server passed**: creates internal Express app, attaches to
server (existing behavior)
  - **Nothing passed**: creates both (existing behavior)
- Updated Express example to pass the Express app directly (the
recommended pattern)

The original `http.Server`-only constructor was designed to match the
`HttpPlugin`'s capabilities, but it led users into a trap: passing
`http.createServer(app)` caused the adapter to attach a second Express
app to the same server, resulting in double request handling. Accepting
the Express app directly is the natural fix. Ideally, we should probably
just not accept an http server and just accept an existing express app.
If someone is managing an express app outside, they can continue doing
that, and they should be responsible for handling the http server too.

Fixes #503

## Test plan
- [x] Existing `express-adapter` tests pass (9/9)
- [x] New test: passing an Express app works for both custom routes and
adapter-registered routes
- [x] Manual: verify Express example compiles and runs correctly

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

examples/http-adapters/express/index.ts

@@ -1,5 +1,6 @@
+import http from 'http';
 import 'dotenv/config';
-import { app, httpServer } from './teams-app';
+import { app, expressApp } from './teams-app';
 
 const port = parseInt(process.env.PORT || '3978', 10);
 
@@ -9,7 +10,8 @@ async function main() {
   // Initialize teams.ts app - this adds /api/messages to your Express app
   await app.initialize();
 
-  // Start your Express server
+  // Start your server — you control the lifecycle
+  const httpServer = http.createServer(expressApp);
   await new Promise<void>((resolve, reject) => {
     httpServer.listen(port, () => resolve());
     httpServer.once('error', reject);

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

@@ -1,10 +1,8 @@
-import http from 'http';
 import express from 'express';
 import { App, ExpressAdapter } from '@microsoft/teams.apps';
 
 // 1. Create your existing Express app with routes
 export const expressApp = express();
-export const httpServer = http.createServer(expressApp);
 
 // Add your custom routes
 expressApp.get('/health', (_req, res) => {
@@ -36,8 +34,8 @@ expressApp.get('/', (_req, res) => {
   `);
 });
 
-// 2. Create Express adapter with your existing server
-export const adapter = new ExpressAdapter(httpServer);
+// 2. Create Express adapter with your existing Express app
+export const adapter = new ExpressAdapter(expressApp);
 
 // 3. Create teams.ts app with the adapter
 export const app = new App({

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

@@ -4,6 +4,7 @@ import http from 'http';
 import os from 'os';
 import path from 'path';
 
+import express from 'express';
 import supertest from 'supertest';
 
 import { ExpressAdapter } from './express-adapter';
@@ -25,6 +26,41 @@ describe('ExpressAdapter', () => {
     }).not.toThrow();
   });
 
+  it('should accept an Express app and handle requests without double handling', async () => {
+    const app = express();
+    app.get('/health', (_req, res) => {
+      res.json({ ok: true });
+    });
+
+    adapter = new ExpressAdapter(app);
+
+    adapter.registerRoute('POST', '/api/messages', async ({ body }) => {
+      return { status: 200, body: { echo: (body as Record<string, unknown>).message } };
+    });
+
+    // User manages the server themselves
+    server = http.createServer(app);
+
+    // Verify custom routes on the Express app still work
+    const healthRes = await supertest(server).get('/health').expect(200);
+    expect(healthRes.body).toEqual({ ok: true });
+
+    // Verify teams route registered by the adapter works
+    const botRes = await supertest(server)
+      .post('/api/messages')
+      .send({ message: 'hello' })
+      .expect(200);
+    expect(botRes.body).toEqual({ echo: 'hello' });
+  });
+
+  it('should throw on start/stop when Express app is passed', async () => {
+    const app = express();
+    adapter = new ExpressAdapter(app);
+
+    await expect(adapter.start(3000)).rejects.toThrow('server lifecycle is managed externally');
+    await expect(adapter.stop()).rejects.toThrow('server lifecycle is managed externally');
+  });
+
   describe('route registration and request handling', () => {
     it('should handle POST requests with JSON body parsing', async () => {
       server = http.createServer();

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

@@ -27,14 +27,24 @@ export class ExpressAdapter implements IHttpServerAdapter {
   readonly use: express.Application['use'];
 
   protected express: express.Application;
-  protected server: http.Server;
+  protected server?: http.Server;
   protected logger: ILogger;
   protected onError?: (err: Error) => void;
 
-  constructor(server?: http.Server, options?: { logger?: ILogger; onError?: (err: Error) => void }) {
-    this.express = express();
-    this.server = server || http.createServer();
-    this.server.on('request', this.express);
+  constructor(serverOrApp?: http.Server | express.Application, options?: { logger?: ILogger; onError?: (err: Error) => void }) {
+    if (serverOrApp instanceof http.Server) {
+      // The adapter handles all requests on this server. Use the adapter's
+      // methods (get, post, use, etc.) to add routes. If you need your own
+      // Express app, pass it in instead and manage the server yourself.
+      this.express = express();
+      this.server = serverOrApp;
+      this.server.on('request', this.express);
+    } else if (typeof serverOrApp === 'function') {
+      this.express = serverOrApp;
+    } else {
+      this.express = express();
+      this.server = http.createServer(this.express);
+    }
     this.logger = options?.logger ?? new ConsoleLogger('ExpressAdapter');
     this.onError = options?.onError;
 
@@ -79,21 +89,27 @@ export class ExpressAdapter implements IHttpServerAdapter {
    * Start the server listening on the specified port
    */
   async start(port: number | string): Promise<void> {
+    const server = this.server;
+
+    if (!server) {
+      throw new Error('Cannot start: server lifecycle is managed externally. Call listen() on your Express app or http.Server directly.');
+    }
+
     return new Promise<void>((resolve, reject) => {
       // Handle startup errors
-      this.server.once('error', (err) => {
+      server.once('error', (err) => {
         if (this.onError) {
           this.onError(err);
         }
         reject(err);
       });
 
-      this.server.listen(port, () => {
+      server.listen(port, () => {
         this.logger.info(`listening on port ${port} 🚀`);
 
         // Set up persistent error listener after startup
         if (this.onError) {
-          this.server.on('error', this.onError);
+          server.on('error', this.onError);
         }
 
         resolve();
@@ -112,8 +128,14 @@ export class ExpressAdapter implements IHttpServerAdapter {
    * Stop the server and close all connections
    */
   async stop(): Promise<void> {
+    const server = this.server;
+
+    if (!server) {
+      throw new Error('Cannot stop: server lifecycle is managed externally. Call close() on your Express app or http.Server directly.');
+    }
+
     return new Promise<void>((resolve, reject) => {
-      this.server.close((err) => {
+      server.close((err) => {
         if (err) {
           reject(err);
         } else {