@haruhimemoe/mirror

Downloads osu! beatmapsets (.osz) from whichever public mirror has them, used by the haruhime.moe tools:

• Failover: tries hinai first, then osu.direct, Mino and Sayobot. A 404 moves on to the next mirror; so do errors, timeouts and answers that aren't a zip.
• Cooldowns: a mirror that looks down (a network error, a timeout, a 429, or 3 failures in a row) is skipped by later downloads until its Retry-After or backoff has passed.
• Zip checks: every archive's first bytes are checked to be a zip before any progress is reported. Mirrors sometimes answer 200 with a JSON error.
• Straight from the mirror: bytes go from the mirror to your code. Nothing is hosted or proxied, and in a browser the mirror answers the browser directly (every mirror here sends open CORS).
• The hinai client: @haruhimemoe/mirror/hinai is the whole hinai client (metadata, availability, downloads), and @haruhimemoe/mirror/testing mocks hinai with msw. They replace @haruhimemoe/hinai, which is deprecated.

npm install @haruhimemoe/mirror zod# orbun add @haruhimemoe/mirror zod

zod (4.0.16 or later in 4.x) is a peer dependency. @haruhimemoe/osu installs with it; only its beatmap shapes are used. If your app imports @haruhimemoe/osu too, keep it on 0.4.x so there's one copy and one BeatmapMeta type. msw 2 is an optional peer, needed only for /testing.

Swap the import paths and remove the old package:

- import { createHinaiClient, HinaiError } from "@haruhimemoe/hinai";- import { hinaiHandlers } from "@haruhimemoe/hinai/testing";+ import { createHinaiClient, HinaiError } from "@haruhimemoe/mirror/hinai";+ import { hinaiHandlers } from "@haruhimemoe/mirror/testing";

Names and behavior are unchanged. Don't keep both packages installed: each has its own HinaiError class, and instanceof fails across them.

import { createMirrorClient, MirrorError } from "@haruhimemoe/mirror";const mirror = createMirrorClient(); // in a browser// On a server, name your tool. Mino refuses server requests without a User-Agent.// const mirror = createMirrorClient({ userAgent: "my-tool/1.0 (https://example.com)" });try {  const { blob, mirror: from, failed } = await mirror.downloadSet(320118, {    onProgress: ({ mirror, loaded, total }) => console.log(mirror, loaded, total),  });  console.log(`got ${blob.size} bytes from ${from} after ${failed.length} misses`);} catch (error) {  if (error instanceof MirrorError && error.retryable) {    // try again after error.retryAfterMs  }}

Set ids, not difficulty ids: downloadSet takes a beatmapset_id.

Throws a RangeError when mirrors is empty, names an unknown id or repeats one, timeoutMs isn't an integer from 1 to 2147483647, or userAgent (on a server) isn't a valid header value.

Resolves to { blob, mirror, failed }: the .osz (typed OSZ_MIME), the id of the mirror that sent it, and a MirrorAttempt for each mirror that failed first.

A set id that isn't a positive integer throws a RangeError before any request.

Each mirror's URL for the set as { mirror, url }, in order, mirrors cooling down last. Use it for plain <a href> links or when the browser should save the file itself.

Each mirror's { mirror, failures, coolingUntil }: failures in a row (404s don't count) and when it's worth asking again, or null.

The hinai client's, passed through. See Metadata and Availability. They reject with a HinaiError.

MIRRORS holds the built-ins by id, and DEFAULT_MIRRORS the default order:

Add your own with a Mirror object:

const mirror = createMirrorClient({  mirrors: [    "hinai",    {      id: "mine",      name: "My mirror",      homepage: "https://example.com",      downloadUrl: (setId, video) => `https://example.com/d/${setId}${video ? "" : "?nv=1"}`,      missingStatuses: [403], // optional: statuses besides 404 and 410 that mean "no such set"    },    "osudirect",  ],});

downloadSet rejects with a MirrorError once every mirror has had its turn:

attempts lists every failed try as { mirror, url, code, status, retryAfterMs }, where code is not_found, http_error, network, timeout or bad_response (a 200 that wasn't a zip).

Aborts reject with the signal's reason, not a MirrorError. So do errors thrown by onProgress.

A network error, a timeout or a 429 cools a mirror down at once. Other failures (a 403, a 5xx, a bad body) often concern one set, so they only cool it down after MIRROR_FAILURE_LIMIT (3) in a row. The wait is the mirror's Retry-After (capped at 60 s), else 1 s, 2 s, 4 s and so on by failures in a row. A download resets the mirror. State lives in the client: make one per app, not per download.

@haruhimemoe/mirror/hinai talks to hinai alone: no failover. Use it for metadata, or when you want hinai's request ids and forensics URLs on every error.

import { createHinaiClient } from "@haruhimemoe/mirror/hinai";const hinai = createHinaiClient(); // in a browser// On a server, say who you are, as the mirror asks:// createHinaiClient({ userAgent: "my-app/1.0 (+https://example.com)" })const controller = new AbortController();// Metadata takes difficulty ids.const { found, missing } = await hinai.getBeatmaps([129891, 75], { signal: controller.signal });for (const [id, meta] of found) console.log(id, meta.artist, meta.title, meta.version);console.log("not on the mirror:", missing);// Availability and downloads take set ids.const { downloadable, reason } = await hinai.getAvailability(39804, { signal: controller.signal });if (downloadable) {  const osz = await hinai.downloadSet(39804, {    video: false,    signal: controller.signal,    onProgress: ({ loaded, total }) => console.log(loaded, total),  });  console.log(osz.size, osz.type); // type is "application/x-osu-beatmap-archive"} else {  console.log("downloads are disabled:", reason);}

getBeatmaps(ids, { signal }) takes difficulty ids. Duplicates are fine.

• Valid ids go to the mirror in requests of 100 (HINAI_BATCH_LIMIT), one after another. If one request fails, the whole call rejects with that error.
• found is a Map from difficulty id to BeatmapMeta: ids, ruleset, title, artist, version, creator, CS/AR/OD/HP, BPM, length, star rating and md5 checksum. The fields are listed in @haruhimemoe/osu.
• missing has every id you passed that isn't in found, once each, in the order you passed them. That covers ids the mirror doesn't know, ids that aren't positive integers, and rows the mirror sent that don't parse as an osu! beatmap.
• A list with no valid ids sends no request.

getAvailability(setId, { signal }) takes a set id and resolves to { downloadable, reason }.

• downloadable is false only when the mirror says downloads are disabled (a DMCA or other takedown). reason is the mirror's more_information text, or null.
• When the mirror doesn't know whether a set is blocked (download_disabled: null), downloadable is true: try the download.
• A set the mirror doesn't know rejects with a HinaiError whose code is not_found.

downloadSet(setId, { video, signal, onProgress }) takes a set id and resolves to a Blob of type application/x-osu-beatmap-archive (OSZ_MIME), held in memory.

• video: false (the default) asks for the archive without its video. The mirror only keeps no-video archives itself, so video: true can be slower.
• The first 4 bytes must be the zip signature (PK\x03\x04), else the call rejects with bad_response.
• onProgress is called once per chunk, only after that check, with { loaded, total }. total is the content-length, or null when the mirror didn't send one or the body turned out longer.
• timeoutMs only covers the wait for the response headers (and, on an error status, reading the mirror's error body). Once the archive streams, only your signal stops a download.
• setDownloadUrl(setId, baseUrl?, video?) builds the same URL without downloading anything.

• Every method takes a signal. An abort rejects with the signal's reason (a DOMException named AbortError, unless you aborted with a reason of your own), not a HinaiError. A signal that's already aborted rejects at once, before any request, even when there's nothing to send (an empty id list). An error thrown by your onProgress also rejects the call as it is.
• createHinaiClient throws a RangeError for a bad baseUrl, timeoutMs or userAgent, and setDownloadUrl for a bad set id or baseUrl.
• getAvailability and downloadSet reject with a RangeError, before any request, for a set id that isn't a positive integer.

Options to createHinaiClient:

Every option, and every method option, also accepts undefined, which means "use the default".

Everything below is exported from @haruhimemoe/mirror/hinai, except getBeatmaps, getAvailability and downloadSet, which are methods on the client. The msw mocks for tests are in Testing.

Client

Methods (on the object createHinaiClient returns) and their shapes

BeatmapMeta itself comes from @haruhimemoe/osu/shapes; this package doesn't re-export it.

Errors and retry

import { backoffDelayMs, createHinaiClient, HinaiError } from "@haruhimemoe/mirror/hinai";const hinai = createHinaiClient();const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));async function downloadWithRetries(setId: number) {  for (let attempt = 1; ; attempt++) {    try {      return await hinai.downloadSet(setId);    } catch (error) {      if (!(error instanceof HinaiError) || !error.retryable || attempt === 4) throw error;      await sleep(backoffDelayMs(attempt, error.retryAfterMs)); // Retry-After, else 1s, 2s, 4s…    }  }}

A HinaiError has:

@haruhimemoe/mirror/testing mocks the mirror for your app's tests with msw 2 (an optional peer: install it yourself). These are the handlers and recorded answers this package tests itself with, so your mocks change when the client does.

import { hinaiHandlers, hinaiUnknownSetHandler } from "@haruhimemoe/mirror/testing";import { setupServer } from "msw/node";const server = setupServer(...hinaiHandlers);// In a test: availability for any set now rejects with not_found.server.use(hinaiUnknownSetHandler);

The handlers answer on https://mirror.hinamizawa.ai only; for another baseUrl, write your own with the recorded answers and fakeOsz.

• Download one or two sets at a time and cache finished files (browsers: OPFS or IndexedDB).
• Identify your tool with userAgent on servers.
• Don't re-host .osz files. Rights holders use each mirror's own takedown process.

Node 22.12 or later, current browsers and workers. ESM only.

MIT