feat: organize route & middleware by sequence

[j03-dev]

• feat: sequence matter
• chore: move redirect to import
• chore: update docstring

Summary by CodeRabbit

Release Notes

• Breaking Changes

  • Removed Router.scope() method; use separate router instances for middleware isolation.

• Changed Behavior

  • Middleware now applies only to routes registered after it within the same router.

• New Features

  • Multiple routers can be attached to the server and are checked in registration order.

• Documentation

  • Comprehensively updated middleware documentation with new organization paradigms and combined examples.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bbf9e80a-3cf3-415f-a742-3e5d88598901

📥 Commits

Reviewing files that changed from the base of the PR and between 6e862f8 and d670d14.

📒 Files selected for processing (8)

• AGENTS.md
• README.md
• oxapy/__init__.pyi
• src/lib.rs
• src/middleware.rs
• src/request.rs
• src/routing.rs
• tests/conftest.py

---

📝 Walkthrough

Walkthrough

Removes the Layer/scope() routing abstraction and replaces it with a flat Router model where each route and middleware carries a sequence counter. Middleware now applies only to routes registered after it within the same router. Multiple routers are stored and checked in attachment order. The scope() API is removed from the Rust implementation, Python stub, and all documentation.

Changes

Router Refactor: Sequence-based Middleware and Layer Removal

Layer / File(s)	Summary
Route & Middleware sequence fields; Router struct overhaul src/routing.rs, src/middleware.rs	Adds sequence: usize to Route (initialized to 0) and Middleware. Removes the Layer struct. Restructures Router to hold count, a flat routes HashMap, and middlewares Vec directly.
Router registration: new, route, middleware, routes src/routing.rs	Router::new initializes the counter/flat-routes layout. Router::middleware stamps count onto each middleware and increments it. Router::route takes ownership of Route, assigns route.sequence = self.count, inserts it, then increments count. Bulk routes() delegates per-route to route().
MiddlewareChain sequence-based cutoff src/middleware.rs	build_middleware_chain accepts route_sequence and short-circuits by returning the bare route_handler when a middleware's sequence exceeds route_sequence, preventing post-route middleware from being applied.
Request dispatch: Layer→Router src/lib.rs, src/request.rs	All routing context fields (ProcessRequest, RequestContext, HttpServer) switch from Layer/layers to Router/routers. try_handle_route iterates ctx.routers and calls router.find(). process_matched_route and execute_route_handler accept Arc<Router>. HttpServer::attach pushes routers into slf.routers.
Python stub: Router.scope() removal and docstring updates oxapy/__init__.pyi	Removes Router.scope() from the public stub. Updates HttpServer.attach(), Router, and Router.middleware() docstrings to describe multi-router ordering and sequence-based middleware semantics.
README, AGENTS.md, and test fixture updates README.md, AGENTS.md, tests/conftest.py	README middleware section rewritten to describe Sequence and Multi-Router paradigms. AGENTS.md notes updated to match. Test fixture removes .scope() call and cleans up a redundant local import.

Sequence Diagram

sequenceDiagram
  participant Client
  participant HttpServer
  participant try_handle_route
  participant Router
  participant MiddlewareChain
  participant PyHandler

  Client->>HttpServer: HTTP request
  HttpServer->>HttpServer: create_request_context (clones routers vec)
  loop for each router in ctx.routers
    HttpServer->>try_handle_route: iterate routers
    try_handle_route->>Router: find(method, path)
    Router-->>try_handle_route: Match or None
  end
  try_handle_route->>HttpServer: process_matched_route(Arc<Router>)
  HttpServer->>MiddlewareChain: build_middleware_chain(route_sequence)
  MiddlewareChain->>MiddlewareChain: skip middleware where sequence > route_sequence
  MiddlewareChain->>PyHandler: call handler via filtered chain
  PyHandler-->>Client: HTTP response

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• j03-dev/oxapy#82: Introduced the Layer-based routing in src/lib.rs, src/request.rs, and src/routing.rs that this PR replaces with the flat Router model.
• j03-dev/oxapy#9: Added the initial MiddlewareChain construction in src/middleware.rs that this PR extends with sequence-based cutoff logic.
• j03-dev/oxapy#84: Refactored src/request.rs's try_handle_route/process_matched_route pipeline that this PR further modifies for Router-based dispatch.

Suggested reviewers

• LucaZH

Poem

🐇 Hoppity-hop, the layers are gone,
No more .scope() to fret upon!
Each router now marches in its own queue,
Middleware only sees routes it came through.
Sequences counted, the order is clear —
A flatter, smarter path from here! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sequence

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}