feat: add download reference and importing update

Author: DecDuck

astro.config.mjs

@@ -15,7 +15,7 @@ export default defineConfig({
         starlightImageZoom(),
       ],
       title: "Drop OSS",
-      logo: { src: "./src/assets/wordmark.png", replacesTitle: true},
+      logo: { src: "./src/assets/wordmark.png", replacesTitle: true },
       social: [
         {
           icon: "github",
@@ -47,6 +47,10 @@ export default defineConfig({
                 { slug: "admin/guides/import-version" },
               ],
             },
+            {
+              label: "Going further",
+              items: [{ slug: "admin/going-further/importing-update" }],
+            },
             {
               label: "Metadata",
               autogenerate: { directory: "admin/metadata" },

src/content/docs/admin/going-further/importing-update.mdx

@@ -0,0 +1,48 @@
+---
+title: Importing an update
+---
+
+import { Steps } from "@astrojs/starlight/components";
+
+If you're using a library source that supports versioning, you can add and import an update for your game! There are two ways to do it:
+
+- Overwrite: completely overwrites the previous version. Simpliest to understand and use.
+- Update-mode: patches the previous version's files, while providing new configuration.
+
+## Overwrite
+
+<Steps>
+1. ### Add your new files
+
+    Add your new files, making note of the folder structure of your library source.
+
+2. ### Follow the import guide again
+
+   Follow the [import guide again](/admin/guides/import-version/), but this time for your new version folder.
+
+</Steps>
+
+## Update mode
+
+You may noticed a toggle in the version import UI called "update mode". This enables update mode, which:
+
+- takes the files from your new version
+- takes the files from your old version
+- pastes the new files over the old files, overwriting where they conflict
+
+You can stack many "update mode" versions on top of each other, and they will pick up files from all of them.
+
+<Steps>
+1. ### Add your new files
+
+    Add your new files, making note of the folder structure of your library source.
+
+2. ### Follow the import guide again
+
+   Follow the [import guide again](/admin/guides/import-version/), but this time for your new version folder.
+
+3. ### Before import, enable update mode
+
+   Click the toggle for "Update mode"
+
+</Steps>

src/content/docs/reference/downloads.mdx

@@ -0,0 +1,32 @@
+---
+title: Download internals
+---
+
+Drop uses a special method to download over HTTP to ensure fast and reliable downloads, while achieving the goals of the [Depot API](https://developer.droposs.org/web/depot#notes). Here's how they work
+
+## Game manifest
+
+On importing a version, Drop generates a "game manifest". You can read more about it on the [Depot API section](https://developer.droposs.org/web/depot#manifest-v2), but what it means for non-developer is that **downloads stay the same speed no matter how many files there are, or how big they are.**
+
+Typical file transfer protocols, like FTP or HTTP, make one request for each file. This is great if you have just one, large file, but if you have lots of little ones, you lose a lot of bandwidth to overhead. Drop minimises this by packing smaller files into larger chunks.
+
+Drop also splits larger files into several, smaller chunks. This is to ensure proper balancing of downloads, and make the chunks easier to manage (since they all are roughly the same size).
+
+:::note
+Due to limitations with 7zip, this is **not true for archive-backed versions.** Drop cannot read parts of files with 7zip, so large files must stay in their own, equally large chunk.
+:::
+
+:::tip
+
+### What's `torrential`?
+
+If you've built the Drop server from source, or checked out the logs in the container, you may have noticed an applcation called `torrential`. `torrential` is a download server that's embedded into Drop, and serves the chunks required for the Depot API, without actually assembling them ahead of time.
+:::
+
+## Delta versions or "Update mode"
+
+While called "update mode" in the UI, internally they are called "delta versions". In practice, they apply files on top of each other, essentially patching previous versions.
+
+However, if you've been paying attention, we don't actually need to do this physically on disk, we can just create a "pseudo-manifest" that pulls chunks from both versions.
+
+The catch is, we can't control what files are packed into each chunk (we can, but we won't know what files will be patched ahead of time, when we're importing). So while we can drop chunks here and there, _if and only if every file has been patched by another version_, we usually end up downloading the entirety of the base version + the patch.