Skip to content

appnote: Fix error in deleting object instances #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
samdbmg merged 3 commits into from
Oct 10, 2025
Merged

appnote: Fix error in deleting object instances #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7d32cf
appnote: Fix error in deleting object instances
samdbmg Sep 29, 2025
343a050
api: Fix confusion on modifying segments
samdbmg Sep 29, 2025
742229e
api: Clarify key_frame_count behaviour on re-use
samdbmg Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions api/TimeAddressableMediaStore.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2003,11 +2003,10 @@ paths:
A service instance MAY support Media Objects that are held in external storage in another TAMS or other media storage system.
The Flow Segment may in that case require the `get_urls` property to provide the information needed by clients to access the Media Object.

Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata as such operations will likely break the idempotency of Segments.
Properties of Media Objects, such as `get_urls`, SHOULD be modified via the [`/objects`](#/operations/GET_objects) endpoints.
They SHOULD NOT be modified at this endpoint, and TAMS instences SHOULD reject such requests with a `400` error.
The list of instances of an object (and associated `get_urls` entries) can be modified via the [`/objects`](#/operations/GET_objects) endpoints, which provides a mechanism to register new instances of an object.

If a client needs to modify a Flow Segment, e.g. to correct metadata such as the `key_frame_count` or add additional URLs to `get_urls`, then the client SHOULD first delete the existing Segment and then write a new one.
Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata such as `key_frame_count`, as such operations will likely break the idempotency of Segments.
If a client needs to modify a Flow Segment, then the client SHOULD first delete the existing Segment and then write a new one.
Copy link
Contributor

@j616 j616 Oct 8, 2025

Choose a reason for hiding this comment

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

Should we also add a note, like those we have elsewhere, warning that setting key_frame_count to a value that conflicts with the Object SHOULD be rejected if that object is in use elsewhere? i.e. don't bring references into conflict with each other.

Copy link
Member Author

@samdbmg samdbmg Oct 9, 2025

Choose a reason for hiding this comment

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

Should clients ignore it if the object is re-used? That would seem like the easiest behaviour to implement I suppose

Copy link
Contributor

@j616 j616 Oct 9, 2025

Choose a reason for hiding this comment

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

I was thinking something like the last para of the main description on https://bbc.github.io/tams/main/index.html#/operations/PUT_flows-flowId . i.e. allow modification if it won't bring anything into conflict. Reject if it will.

Copy link
Member Author

@samdbmg samdbmg Oct 10, 2025

Choose a reason for hiding this comment

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

After discussion, tweaked in 0338ef6 to make expectation clearer

The behaviour is undefined if the Segment exists and the service may return a 400 error response.

For successful creation of all Segments in the request a 201 response should be provided.
Expand All @@ -2016,11 +2015,13 @@ paths:

Clients are expected to decide how to break content into Media Objects, however those Objects SHOULD be large enough to avoid excessive round trip overheads in the underlying store (_e.g._ of the order of several megabytes) and where codecs with temporal re-ordering are used, Object SHOULD contain complete GOPs or decodable units.

For Media Objects that have been re-used from other Flows, the `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use:
For Media Objects that have been re-used from elsewhere, the `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use:
- The `timerange` field indicates the new Segment's position in the Flow
- The sample associated with the start of the `timerange` MUST be the one selected by `sample_offset`
- Likewise, the sample associated with the end of the `timerange` MUST be the one selected by `sample_offset + sample_count - 1`, unless `timerange` has an exclusive end, in which case it will be `sample_offset + sample_count`.
- The timerange of the Segment MUST NOT overlap any other Segment in the same Flow.

When re-using Media Objects, requests which change object properties (e.g. `key_frame_count`) SHOULD be rejected.
operationId: POST_flows-flowId-segments
tags:
- FlowSegments
Expand Down
5 changes: 3 additions & 2 deletions docs/appnotes/0018-managing-multiple-object-instances.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,12 +108,13 @@ Example POST body to `/objects/{objectId}/instances`:

### Deleting an Object Instance

Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/get_urls` with the relevant `storage_id` in the query string.
Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/instances` with the relevant `storage_id` in the query string.
However attempting to delete the last instance of a media object should be rejected: this requires deleting the referencing Flow Segments instead.

Example DELETE request:

```text
http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/get_urls?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc
http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/instances?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc
```

Once deleted, this instance will no longer be advertised in `get_urls` on the `/objects/{objectId}` endpoint or on the `/flows/{flowId}/segments` for Flow Segments which use the Media Object.
Expand Down
Loading