feat: This is a simplification of the Consumer API Spec

[madpah]

This is draft PR that follows the Slack discussions here and here - supported by the attached Zoom Whiteboard (also here) where @nscuro and myself considered, from the Consumer perspective a simplification whilst also consider (as discussed during OWASP Hackathon) the necessary support for Product Versioning.

Revised API Flow (Main Flow)

sequenceDiagram
    actor Client
    Client->>TEA Service: POST /product/search with TEI
    TEA Service-->>Client: TEA Product returned
    Note over TEA Service: This includes a list of TEA Collection identifiers

    loop For every TEA Collection identifier
    Client->>TEA Service: GET /collection/{id}/latest
    TEA Service-->>Client: TEA Collection returned
    Note over TEA Service: This includes all TEA Artifacts in the TEA Collection
    end

References / Workings

Revised simplified data model suggestion (data model, not API Spec):

Worked examples:

FYI @stevespringett

[taleodor]

There are great ideas here, but I feel like the logic breaks when we try to define the concepts of "unversioned product" and "latest versions of components".

Observe that:

• A set of components may change between product releases (say, we dropped, added or replaced an upstream component)
• "Latest" release is frequently not clearly defined, i.e. may a "pre-release" be considered latest?
• Let's assume we defined "Latest" - this would imply that we still need binding for all Component Releases to be able to select the "Latest" among them. That means that the "Component" object entity is still present, just hidden in the model. Of course, we may let implementations work this out, but if this is already clear that the "Component" entity must exist in any case, why not have that added explicitly to the spec? Similar reasoning can be applied to "Product" -> "Product Releases" relationship.

If we respect these limitation, this will actually become very close to the existing spec with certain updates. Particularly, what I really like about this PR is "/product/search" POST call. However, I don't think it's a replacement for /product/{uuid} due to limitations mentioned above.

[nscuro]

@taleodor "Latest" release is frequently not clearly defined, i.e. may a "pre-release" be considered latest?

I would suggest to not try to infer "latest" somehow - this is bound to fail due to the various ambiguities in versioning and release patterns. Instead, let's let publishers explicitly define what version is "latest". This mirrors what you can do in GitHub Releases, and FWIW, it's a mechanism that DT has adopted as well.

@taleodor Let's assume we defined "Latest" - this would imply that we still need binding for all Component Releases to be able to select the "Latest" among them. [...] Similar reasoning can be applied to "Product" -> "Product Releases" relationship.

Possibly. Excuse my ignorance, and this is likely because I joined the effort so late, but where does the need to determine the "latest" component release stem from?

Are we trying to mix transparency artifact exchange with generalized component (version) discovery? Doesn't it suffice for TEA to track component versions as-is?

I get the need for this on the product level, but components?

[taleodor]

@nscuro

I would suggest to not try to infer "latest" somehow - this is bound to fail due to the various ambiguities in versioning and release patterns. Instead, let's let publishers explicitly define what version is "latest". This mirrors what you can do in GitHub Releases, and FWIW, it's a mechanism that DT has adopted as well.

GitHub Releases has no concept of latest, I demonstrated this on one of the calls, can repeat today. Essentially, it may have releases from different streams all mashed together without clear order. Similarly, for DT, it's just a flag, but sometimes it's not meaningful. I.e., a project supports 2 major or minor versions (in semver) at the same time, each of them has their own latest.

Possibly. Excuse my ignorance, and this is likely because I joined the effort so late, but where does the need to determine the "latest" component release stem from?

Component is an upstream dependency of Product. If there is a newer Component Release, as a developer / DevSecOps, I would like to migrate to that, especially if it has security updates.

So the full example is like this -

1. I'm using library ACMElib v.1.1.0
2. I want to know if there is a newer version available
3. ACMElib just released v.1.1.1 (which is a security patch for v.1.1.0), as well as v.1.2.0 (which is a new feature release).
4. I want TEA to inform me that v.1.1.1 is the one I can immediately upgrade to, while 1.2.0 is also there, but requires more testing since it's a feature update.

[nscuro]

GitHub Releases has no concept of latest, I demonstrated this on one of the calls, can repeat today. Essentially, it may have releases from different streams all mashed together without clear order. Similarly, for DT, it's just a flag, but sometimes it's not meaningful.

Oh, I'm fully with you on that. It's not perfect, but it's one of those things that are "good enough" for most applications. It is more akin to "latest and greatest", instead of "latest of stream XYZ".

I.e., a project supports 2 major or minor versions (in semver) at the same time, each of them has their own latest.

What I have seen from TEA so far would also not cater to this (I may just have missed it). Are you arguing against having the concept of "latest" altogether? I think that would drastically simplify things.

If there is a newer Component Release, as a developer / DevSecOps, I would like to migrate to that, especially if it has security updates.

I would challenge if that is a use case TEA should cater to. There is already a vast array of tooling out there that informs about (and performs) version updates. A good chunk of versioning logic is different in each ecosystem, and even within those the rules are not always clear and fully enforced. IMO, TEA should act as a supplement to those (i.e. lookup more info about versions you're considering updating to).

I feel this inflates the TEA spec and deviates from it's primary goal (the exchange), but I respect if this is a direction the WG has decided TEA should go.

[taleodor]

What I have seen from TEA so far would also not cater to this (I may just have missed it). Are you arguing against having the concept of "latest" altogether? I think that would drastically simplify things.

Yes, I don't think we should have the concept of latest. Container images supported it and it almost immediately became an anti-pattern. Instead, I believe we should keep the split between Component and Component Release and Product and Product Release. Then the API consumer would have options what to do with that (similar to the existing GitHub Releases workflow).

In the practical sense of this PR, it means that if a user searches for TEI without version, this leads to a Product that lists all available versions and not to some latest version. And it should work the same way for Components. Products and Components are not that different.

I would challenge if that is a use case TEA should cater to. There is already a vast array of tooling out there that informs about (and performs) version updates.

The novelty here is that TEA would have publisher supplying these data in a structured format. My understanding is that existing tooling should use publisher's TEA to make decisions rather than 3rd party heuristics. This is something that is better to discuss on the call though for establishing common approach.

[nscuro]

In the practical sense of this PR, it means that if a user searches for TEI without version, this leads to a Product that lists all available versions and not to some latest version. And it should work the same way for Components. Products and Components are not that different.

Pragmatic, I like it.

Edit: I think the intention behind returning the "latest" version for a TEI without version is specifically for cases where a product doesn't really have a version. But I guess using a pseudo-version for such products would work just as well.

My understanding is that existing tooling should use publisher's TEA to make decisions rather than 3rd party heuristics.

If this is a goal then we should document it. I fear the tea-usecases.md doc may be horribly outdated at this point.