[Router] Add custom callbacks service

[1Yanik3]

This PR adds a way to call custom callbacks at two points in the code base, allowing the router to be used in places where custom business logic is required. The implementation is inspired by litellm's callback system.

The first point is right after a request comes in, where you can validate the request and return a response overwrite, which will return that response to the user and end the request. This can be used for api-key validation.

The second point is after a request has finished completely. This is achieved using background tasks, so it's non-blocking and can be used for logging.

More locations and callbacks can of course be added later, I suggest starting with only these two for now.

The way you define these points is by implementing an abstract class in a file and passing that file with:

vllm ... --callbacks custom_callbacks_example.proxy_handler_instance

And this is a reference implementation of how you can hook into the endpoints.

# custom_callbacks_example.py

from fastapi import Request, Response

from vllm_router.services.callbacks_service.custom_callbacks import CustomCallbackHandler

class MyCustomCallbackHandler(CustomCallbackHandler):
    def pre_request(self, request: Request, request_body: bytes, request_json: any):
        return Response("I'm a teapot", 418)

    def post_request(self, request: Request, response_content: bytes):
        with open("/tmp/response.txt", "ab") as f:
            f.write(response_content)


proxy_handler_instance = MyCustomCallbackHandler()

I'm open for improvement suggestions if you have any.

CLOSES #186

BEFORE SUBMITTING, PLEASE READ THE CHECKLIST BELOW AND FILL IN THE DESCRIPTION ABOVE

---

• Make sure the code changes pass the pre-commit checks.
• Sign-off your commit by using -s when doing git commit
• Try to classify PRs for easy understanding of the type of changes, such as [Bugfix], [Feat], and [CI].

Detailed Checklist (Click to Expand)

Thank you for your contribution to production-stack! Before submitting the pull request, please ensure the PR meets the following criteria. This helps us maintain the code quality and improve the efficiency of the review process.

PR Title and Classification

Please try to classify PRs for easy understanding of the type of changes. The PR title is prefixed appropriately to indicate the type of change. Please use one of the following:

• [Bugfix] for bug fixes.
• [CI/Build] for build or continuous integration improvements.
• [Doc] for documentation fixes and improvements.
• [Feat] for new features in the cluster (e.g., autoscaling, disaggregated prefill, etc.).
• [Router] for changes to the vllm_router (e.g., routing algorithm, router observability, etc.).
• [Misc] for PRs that do not fit the above categories. Please use this sparingly.

Note: If the PR spans more than one category, please include all relevant prefixes.

Code Quality

The PR need to meet the following code quality standards:

• Pass all linter checks. Please use pre-commit to format your code. See README.md for installation.
• The code need to be well-documented to ensure future contributors can easily understand the code.
• Please include sufficient tests to ensure the change is stay correct and robust. This includes both unit tests and integration tests.

DCO and Signed-off-by

When contributing changes to this project, you must agree to the DCO. Commits must include a Signed-off-by: header which certifies agreement with the terms of the DCO.

Using -s with git commit will automatically add this header.

What to Expect for the Reviews

We aim to address all PRs in a timely manner. If no one reviews your PR within 5 days, please @-mention one of YuhanLiu11
, Shaoting-Feng or ApostaC.

[YuhanLiu11]

Thanks for this great PR! @1Yanik3 We will take a look soon.

[vMaroon]

I think such logical modifications should be reflected in a technical document (e.g., in project docs) associated with the mutated component - in this case the router.

It might make sense to begin writing technical architecture docs, and make updating them mandatory in logic changing PRs.

[1Yanik3]

I think such logical modifications should be reflected in a technical document (e.g., in project docs) associated with the mutated component - in this case the router.

It might make sense to begin writing technical architecture docs, and make updating them mandatory in logic changing PRs.

@vMaroon Thank you for the suggestion, you raise a very good point. I've added docs relating to how to use this feature to docs/source/user_manual/router/cmd.rst, which seemed like the best location.

I think starting full technical architecture docs is a bit out of scope for this PR though, but I agree that long term those would make sense.

[Shaoting-Feng]

Can you fix the failing check? Thanks!

[1Yanik3]

Can you fix the failing check? Thanks!

Sorry for the delay, I forgot to ping you earlier. I've fixed the issues and all test are now passing locally so we should be good to go.