docs(sovd-api): add locks requirements and architecture - #395
Conversation
📊 Coverage Report (unit + DoIP/CAN/mixed integration)Total line coverage: 74.0% |
945e6c6 to
2db5e1d
Compare
f666059 to
b89aae4
Compare
alexmohr
left a comment
alexmohr
left a comment
There was a problem hiding this comment.
couple of questions, mainly about the lock pre-emption :)
| :links: arch~sovd-api-lock-vehicle-blocking | ||
| :status: draft | ||
|
|
||
| When a vehicle lock is held by a client, any other client's attempt to acquire an ECU |
There was a problem hiding this comment.
| When a vehicle lock is held by a client, any other client's attempt to acquire an ECU | |
| When a vehicle lock is held by a client, any other clients attempt to acquire an ECU |
| would violate that claim. | ||
|
|
||
|
|
||
| .. req:: Lock Priority Preemption |
There was a problem hiding this comment.
q: Is this an optional mechanism that can be disabled or will we make this mandatory? Not sure this is wanted by every OEM.
There was a problem hiding this comment.
yes, you get the option to implement this in a plugin (e.g. security), if you don't implement it, the standard is for the lock request to be denied
see `req~sovd-api-lock-priority:
If no vendor mechanism is configured, or if the mechanism does not grant preemption, conflicting POST requests are rejected with HTTP 423 as normal.
| :links: arch~sovd-api-lock-defunct | ||
| :status: draft | ||
|
|
||
| When a lock is preempted by a higher-priority client it must transition to a |
There was a problem hiding this comment.
q: I do understand that certain operations like flashing should be done by clients with a high prio, so they won't get pre-empted. But what if a low prio client starts flashing too and then gets pre-empted. Do we abort to flash transfer or do we deny the pre-emption in this case? (I.e. the 'apply' of an runtime update is rejected when a flash transfer is running)
An alternative could be that certain operations are bound to a given lock priority, but that's probably something to implement in OEM side but OpenSOVD would have to provide the interfaces for this.
There was a problem hiding this comment.
In practice it'll not just be a client, but a client + additional vendor specific additional information, which can be used to distinguish between different use-cases from the same client. Usually only a single client with a single specific additional data would be granted this type of prioritization which should then be the highest, but it's up to individual OEMs to define that.
| - ``x_sovd2uds_broken_by`` -- the identity of the preempting client, as returned | ||
| by the vendor mechanism. | ||
| - ``x_sovd2uds_broken_at`` -- the ISO 8601 timestamp at which preemption occurred. | ||
| - ``x_sovd2uds_current_holder`` -- identity of the current lock holder |
There was a problem hiding this comment.
q: What's the usecase for broken by and current holder, in most cases they will be equal, except the In general, wouldn't it be nice then to return the current lock holder when locking a resource is rejected?
There was a problem hiding this comment.
In most cases yes, but when a lock was only broken for a short time, and there is no current holder, the client can directly reattempt to get a lock. this would mostly be the case when someone is doing manual diagnostics (e.g. low frequency of request), and a quick higher prioritizes automated client doing a quick read from data.
There was a problem hiding this comment.
returning the current lockholder when locking is rejected can also be added, but it would then be an additional parameter in the locking response error parameters for the regular lock request
| side-effects associated with acquiring and releasing a functional group lock. | ||
|
|
||
|
|
||
| .. arch:: Vehicle Lock Blocks Child Lock Acquisition |
There was a problem hiding this comment.
question: If a low prio client is holding a vehicle lock and the high prio client wants an ECU lock, will the low prio client be pre-empted anyway? Same question for functional groups, when the high prio client wants an ECU that is part of a low prio locked functional group.
There was a problem hiding this comment.
lock preemption is only defined for vehicle locks, because it requires additional data to the client id. So a client can't request a higher prio lock for the ecu only, so it'll be rejected.
github-actions
Bot
added
changes requested
Add 9 requirements and 9 matching architecture elements covering the SOVD lock API: CRUD endpoints, exclusivity, expiration, ECU and functional-group enforcement, vehicle-level blocking, priority preemption, defunct lock lifecycle, and HTTP 409 error semantics. Also improve plantuml auto-detection in conf.py by falling back to shutil.which() before the hardcoded JAR path.
The requirement referenced a non-existent endpoint path
/components/{ecu-name}/files/{file-name}. Updated to reflect the actual
bulk-data endpoints used by the implementation.
The architecture sequence diagram referenced a 'Diagnostic Kernel'
participant that does not exist. The handler calls FileManager directly;
replaced the participant and corrected call signatures (list/get) and
removed the non-existent variant parameter.
b89aae4 to
f0fa360
Compare
github-actions
Bot
added
needs review
|
Duplicate-code check passed - no duplication found in changed files. |
2 participants
Summary
Add 9 requirements and architecture elements covering the SOVD lock API: CRUD endpoints, exclusivity, expiration, ECU and functional-group enforcement, vehicle-level blocking, priority preemption, defunct lock lifecycle, and HTTP 409 error semantics.
Also improve plantuml auto-detection in conf.py by falling back to shutil.which() before the hardcoded JAR path,
and fixes an error in the embedded files requirements (wrong path).
Checklist
Related
Notes for Reviewers