Skip to content

refactor: extract request handlers from A2AExpressApp#162

Merged
swapydapy merged 11 commits into
mainfrom
ishymko/express-middlewares
Nov 13, 2025
Merged

refactor: extract request handlers from A2AExpressApp#162
swapydapy merged 11 commits into
mainfrom
ishymko/express-middlewares

Conversation

@ishymko

@ishymko ishymko commented Nov 3, 2025 •
edited
Loading

Copy link
Copy Markdown
Member

Description

As a preparation step for REST support proposed in #142, extract Express.js handlers from A2AExpressApp to allow assembling your own app using Express.js API directly for specifying individual paths and middlewares, rather than wrapping it in A2AExpressApp:

// const a2aRequestHandler = . . .

const app = express();

// Minimal example:
app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: a2aRequestHandler }));
app.use(jsonRpcHandler({ requestHandler: a2aRequestHandler }));

// Advanced example:
app.use(myCustomMiddleware());
app.use('/.well-known/custom-agent-card.json', myCustomAgentCardMiddleware, agentCardHandler({ agentCardProvider: a2aRequestHandler }));
app.use('/a2a/jsonrpc', myJsonRpcMiddleware, jsonRpcHandler({ requestHandler: a2aRequestHandler }));
app.use('/a2a/api', restHandler({ requestHandler: a2aRequestHandler }));

No logic changes to existing handlers, they are moved as is. Also A2AExpressApp is switched to use new handlers without behavior changes.

Note: new functions are not exported via index.ts yet, it will be done together with updating docs and examples once REST support is done.

Re #137

@ishymko ishymko force-pushed the ishymko/express-middlewares branch from 97b3cea to 4832e2e Compare November 3, 2025 15:10
@ishymko ishymko marked this pull request as ready for review November 3, 2025 15:15
@ishymko ishymko requested a review from yarolegovich November 3, 2025 15:38
@ishymko

ishymko commented Nov 3, 2025

Copy link
Copy Markdown
Member Author

/gemini review

gemini-code-assist[bot]
gemini-code-assist Bot reviewed Nov 3, 2025
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request effectively refactors the Express.js request handlers out of A2AExpressApp into their own dedicated files, agent_card_handler.ts and json_rpc_handler.ts. This is a great step towards better modularity and prepares the codebase for future REST support as described. The logic has been moved without behavior changes, and A2AExpressApp is correctly updated to use these new handlers. My review includes a few minor suggestions to improve consistency and adhere to common best practices, such as using express.Router() consistently and improving code style for better readability and safety.

Comment thread src/server/express/a2a_express_app.ts Outdated
Comment thread src/server/express/agent_card_handler.ts Outdated
Comment thread src/server/express/agent_card_handler.ts Outdated
Comment thread src/server/express/json_rpc_handler.ts Outdated
@ishymko ishymko force-pushed the ishymko/express-middlewares branch from 4832e2e to 6c75c53 Compare November 3, 2025 15:51
@ishymko

ishymko commented Nov 3, 2025

Copy link
Copy Markdown
Member Author

/gemini review

gemini-code-assist[bot]
gemini-code-assist Bot reviewed Nov 3, 2025
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request does a great job of refactoring the Express.js handlers out of A2AExpressApp for better modularity and composability. The extraction into agentCardHandler and jsonRpcHandler is clean. However, I've identified a significant behavioral change related to middleware ordering that contradicts the goal of having no behavior changes in A2AExpressApp. I've also noted a minor issue with a leftover log message. My comments provide details on these points.

Comment thread src/server/express/a2a_express_app.ts Outdated
Comment thread src/server/express/json_rpc_handler.ts Outdated
Comment thread src/server/express/json_rpc_handler.ts Outdated
@ishymko ishymko force-pushed the ishymko/express-middlewares branch from 352f44e to 3eaefe1 Compare November 3, 2025 16:35
@ishymko

ishymko commented Nov 4, 2025

Copy link
Copy Markdown
Member Author

/gemini review

gemini-code-assist[bot]
gemini-code-assist Bot reviewed Nov 4, 2025
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request does a great job of refactoring the request handling logic out of A2AExpressApp into separate, composable Express handlers. The code is well-structured and the extraction seems to correctly preserve the existing behavior. My review includes a few suggestions for improvement:

  • Addressing redundant middleware application in A2AExpressApp.
  • Improving the uniqueness of Server-Sent Event IDs.
  • Simplifying the API of jsonRpcHandler to hide implementation details.

Overall, this is a solid refactoring that improves the modularity of the codebase.

Comment thread src/server/express/a2a_express_app.ts
Comment thread src/server/express/json_rpc_handler.ts
Comment thread src/server/express/json_rpc_handler.ts
swapydapy
swapydapy requested changes Nov 7, 2025
View reviewed changes
Comment thread src/server/express/agent_card_handler.ts
Comment thread src/server/express/agent_card_handler.ts Outdated
Comment thread src/server/express/json_rpc_handler.ts
Comment thread src/server/express/json_rpc_handler.ts
Comment thread src/server/express/a2a_express_app.ts
Comment thread src/server/express/json_rpc_handler.ts
@ishymko ishymko mentioned this pull request Nov 12, 2025
Closed
@ishymko ishymko requested a review from swapydapy November 12, 2025 10:53
@swapydapy swapydapy merged commit 3d23332 into main Nov 13, 2025
4 checks passed
@swapydapy swapydapy deleted the ishymko/express-middlewares branch November 13, 2025 02:54
@ishymko ishymko mentioned this pull request Nov 13, 2025
Merged
4 tasks
@ishymko ishymko mentioned this pull request Nov 28, 2025
Merged
@ishymko ishymko mentioned this pull request Dec 10, 2025
Merged
ishymko added a commit that referenced this pull request Dec 10, 2025
@ishymko
docs: update docs for 0.3.6 (#246)
8da480e 
# Description

1. Update README.md, sample agents and sample CLI to use new APIs
introduced in #162 (extract middlewares from `A2AExpressApp`) and #198
(transport-agnostic client).
2. Mark `A2AExpressApp` and `A2AClient` as deprecated.
3. Ensure samples and TCK import via index files only to "test" that all
required types are exported.
4.  Consolidate all `@example` tags to use ` ```ts `.
@ishymko ishymko mentioned this pull request Mar 18, 2026
Closed
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@swapydapy swapydapy swapydapy approved these changes

@yarolegovich yarolegovich yarolegovich approved these changes

@guglielmo-san guglielmo-san guglielmo-san approved these changes

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@ishymko @swapydapy @yarolegovich @guglielmo-san