2023 09 05

2023-09-05 20:00

Netlify / Starlight migration PR

• Netlify is only free for open source projects if we follow certain criteria (Netlify open source policy)
• use Funkwhale's Code of Conduct (https://funkwhale.audio/en_US/code-of-conduct)
• use CC BY-SA as license for the spec (https://creativecommons.org/licenses/by-sa/4.0/)
• https://github.com/expressive-code/expressive-code

Versioning endpoint PR

• Change /{major_version} to v1 for all endpoint for clarity in the docs.
• /versions and /v1/capabilities will be kept as separate endpoints, as currently foreseen.
• /versions endpoint will not include the URL of the endpoint.
• Change the json response of /versions to return a versions object containing an array (in line with XML)
• Change the response of /versions to include minor versions as separate info, to avoid string parsing by the client. (Patch versions are not included here because they're not behavioral changes, thus not needed to know by the server or client.)

{
    "versions": [
        "v1": { "minor": 6 },
        "v2": { "minor": 0 }
    ]
}

We'll bake in major versions in urls.

GET https://openpodcastapi.com/v1/subscriptions

If we have a new major version, but we have an endpoint that didn't change, e.g. /v2 in the back-end can simply redirect /v1 code.

Episodes endpoint

• State of episode identification (notes of 2023-05-30)

Identification methods comparison

We talked about such a comparison here

• Static fetch-hash: (doesn't need to be a hash?) once-calculated hash/identificator for an episode that is then used for identification. If the episode metadata changes, the fetch-hash will remain the same (unless a client decides to 'duplicate' an episode if it considers it is too different??).
• Dynamic fetch-hash: hash that is calculated on-the-fly following a specific algorithm so that it is the same for each client/server. If the episode metadata changes, the fetch-hash will change as well.
• GUID: use the GUID field, if an episode doesn't have one, generate it

test case ✖✔	🎉Static fetch-hash / generated GUID🎉	Dynamic fetch-hash	GUID from the feed
rss feed without episode guids IDs need to be generated once	✔	✔	✔
rss feed with 2 duplicate guids We would see them as the same episode in each case - but we'd accept this (consider them effectively the same episde, and sync changes between the 'two' episodes) The client can decide whether the episodes are the same or whether they are different - if they are different, GUIDs from the feed cannot be used!!	✔	✔	✖
guid changes for a given episode in the rss feed Deduplication endpoint necessary, deduplicate client-side?	✔	✖	✔

• We have to accept that a) an episode may not have a GUID and b) the GUID can contain anything/any type of character.

• Our choice of input fields for a fetch-hash and which metadata changes, affects

  • dynamic fetch-hash --> always different
  • static fetch-hash --> are different if
    • two clients independently fetch RSS feeds, catch episodes locally & calculate fetch-hash, but information affecting fetch-hash has changed in the meantime
    • single client has deduplication logic and determines that episode is not known but new

• Sync first, post later. This is to avoid 'race condition'

• We want to push identification/deduplication to clients as much as possible.

  • If we are more precise for episode identification at server level, we are more likely to have 'different' episodes (e.g. in case of duplicate GUIDs; custom fetch-hash will lead to separate IDs).
  • In this situation, clients can make a decision, using the /deduplication endpoint.

• clear 'winner' in the table: static fetch-hash fetch-GUID (we want the format to be a GUID, not a hash).

• How do clients match episodes in the local feed/database, with the episodes from the server?

  • See https://pad.funkwhale.audio/oCfs5kJ6QTu02d_oVHW7DA#Fetch-hash --> "Good practice/required: store all 3" + Matching proposal in pseudo-code.
  • If we were to use a generated hash to fetch information, this can change at any time and we would need to perform matching client-side to make sure the client has the fetch hash as well. (In that sense a GUID is equally unreliable as a hash.) For this reason, it's better to use the GUID format to sync as it's more standard. The client will still need to perform matching of information such as link, enclosure, media, podcast GUID to assign the fetch GUID in the payload to the local entry.
  • Who generates the fetch-GUIDs? Same as with subscriptions - clients CAN generate and send them to the server. But they can also leave the field empty and the server will generate and respond with it. The client CAN (?) put a temporary identifier into the request (e.g. the local DB index) that the server will reflect so that the client can match the episodes from the server response more easily.
  • Matching doesn't need to be done server-side, if clients respect fetch first post later.

(Authentication)

tags: project-management meeting-notes OpenPodcastAPI