Repository navigation
Python: fix(devui): validate conversation metadata at the route boundary - #10361
tang-ontheway wants to merge 2 commits into
Conversation
|
tang-ontheway please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
There was a problem hiding this comment.
🟡 Changes recommended
The metadata validator silently coerces non-string keys, allowing distinct entries to collapse and lose data instead of enforcing the documented string-key/string-value contract.
1 open issue
What changed in this PR
This PR addresses #9860 by hardening DevUI conversation metadata handling so malformed writes cannot break conversation listing.
Changes:
- Validates metadata at the store boundary and normalizes explicit
nullto an empty map. - Returns HTTP 400 for metadata validation errors while preserving 404 responses for missing conversations.
- Adds defensive metadata reads and regression tests for store and route behavior.
| File | Description |
|---|---|
python/packages/devui/tests/devui/test_conversation_metadata.py |
Adds validation, null-normalization, legacy-read, and HTTP response tests. |
python/packages/devui/agent_framework_devui/_server.py |
Maps metadata validation failures to HTTP 400. |
python/packages/devui/agent_framework_devui/_conversations.py |
Adds write validation and defensive reads for stored metadata. |
Review effort: Balanced
| raise ConversationMetadataValidationError( | ||
| "metadata values must be strings; invalid keys: " + ", ".join(sorted(str(key) for key in invalid_values)) | ||
| ) | ||
| return {str(key): value for key, value in metadata.items()} |
Nick (surlymochan)
left a comment
There was a problem hiding this comment.
Verified the validation path and the route mapping: None normalizes to {}, non-map and non-string values raise ConversationMetadataValidationError, create answers 400 with the OpenAIError shape, update answers 400, and a missing conversation still answers 404. The legacy-tolerance read path (_stored_metadata dropping non-string values instead of failing) is the right call for pre-validation rows.
Three consistency questions:
- The two routes return different 400 shapes: create builds an
OpenAIError(invalid_request_error/invalid_metadata), while update raises a plainHTTPException(400)withdetail=str(e). Is that split intentional, or should update use the sameOpenAIErrorbody so clients see one error contract? - Precedence:
update_conversationin the store checks existence before validating metadata, so invalid metadata on a missing conversation answers 404, not 400. The test pins 404 for valid metadata on a missing id, but the invalid-metadata-plus-missing-id combination is unpinned. Is 404-first the intended precedence? - Keys are coerced with
str(key)rather than rejected, so a direct store caller passing non-string keys (e.g.{7: "x"}) silently gets{"7": "x"}, even though the contract says "a map of string keys to string values". Intended leniency, or should non-string keys raise like non-string values do?
Also confirmed: the update route's metadata=None clearing the map (200 + {}) matches the docstring's "explicit None is normalized to an empty map" — flagging only because clearing on None is a behaviour worth a deliberate decision, not an accident.
|
Thanks Nick (@surlymochan) for the thorough check and Copilot for catching the key coercion! Addressed in
Verified with |

Motivation & Context
The DevUI conversation create and update routes accepted any JSON value as
metadataand stored it verbatim. One such write was enough to breakGET /v1/conversationsfor every caller until the server restarted, while single conversation reads kept working, which made the failure look random:The crash was in
list_conversations_by_metadata(_conversations.py), whereconv_data.get("metadata", {}).copy()returned the stored non-map value and.copy()raised. The Conversations API contract says metadata is a map of string keys to string values, so the write should have been rejected in the first place.Description & Review Guide
validate_conversation_metadata()is now applied at the store boundary increate_conversation()andupdate_conversation(). Metadata that is not a map of string keys to string values raisesConversationMetadataValidationError; an explicitNoneis normalized to an empty map.ConversationMetadataValidationErrorto400, so a malformed write is a client error at the boundary instead of a stored value that breaks a later read.get_conversation(),list_conversations_by_metadata()) now go through_stored_metadata(), which reports a value that is not a map as no metadata at all. This keeps conversations that were stored before the validation existed readable and keeps the list endpoint from failing on them.400; the stored state stays valid, soGET /v1/conversationscan no longer be taken down by one bad write.404, and valid metadata behaves exactly as before.Conversationmodel and the request/response shapes are untouched.metadata: nullto an empty map on update is the expected behavior, or whether it should be rejected as well.Related Issue
Fixes #9860
AI Assistance
AI assistance details: An AI coding assistant helped locate the metadata handling path, draft the regression tests, and prepare this description. The analysis, the reproduction and the test results were verified by me against
mainat commit92838b6.Contribution Checklist
breaking changelabel (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.