The 1 GB file ceiling, and how much headroom is left

"""Measure how close your uploads are to the ceiling that will stop them.

Read only. files.list, auth.test and team.info are reads. Nothing here mints an
upload URL, sends a byte anywhere, deletes a file or fetches a url_private: a
bot token with files:read is enough, and every repair is printed.

Slack caps one file at 1 GB. That number is almost never the one you meet. The
byte transfer in the middle of the modern upload goes to a storage host that is
not a Slack API host, over a plain HTTP request that inherits none of your
Slack client's timeout or retry configuration, and it is the step that gives up
first. So the question is not "which upload failed" but "how much room is
left", and that is a distribution rather than an error.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("slack_file_sizes")

API = "https://slack.com/api/"

# The documented per-file ceiling: one gibibyte. Everything below it is a
# property of your link and your HTTP client rather than of Slack, which is why
# the other two edges are arguments with soft defaults.
CEILING = 1024 ** 3
# Where the plain byte transfer starts being the problem instead of the size.
# Drawn from what people report rather than from any published number; replace
# it with the size at which your own uploads got slow.
TRANSFER_BAND = 25 * 1024 * 1024
# What counts as no room left. A file this close to the cap crosses it on the
# day the data grows, which is a date rather than a possibility.
NEAR = 0.75

# The bands that are worth waking somebody for. Kept as a constant so the rows
# printed and the number in the verdict cannot drift apart.
FINDINGS = ("over-ceiling", "no-headroom", "transfer-band")


def human(size):
    """Bytes as something a person can read. Pure."""
    try:
        n = float(size)
    except (TypeError, ValueError):
        return "?"
    for unit in ("B", "KB", "MB", "GB"):
        if abs(n) < 1024 or unit == "GB":
            return "%.1f %s" % (n, unit)
        n /= 1024.0
    return "%.1f GB" % n


def band(f, ceiling=CEILING, transfer=TRANSFER_BAND, near=NEAR):
    """Which size band is one file in? Pure. Returns (band, size, detail).

    The bands are deliberately not "ok" and "too big". A file at 79% of the
    ceiling is not a failure today and is a scheduled one, and a file in the
    transfer band fails on a slow morning and succeeds on a fast one. Those are
    the two states this note exists to name.

    empty is classified and then handed off: a registered file of length zero
    is the upload sequence stopping in the middle, not a size, and counting it
    here would put a stalled transfer and a growing export in one bucket.
    """
    row = f or {}
    if row.get("is_external"):
        return ("external", 0, "hosted outside Slack, so the bytes and their limits "
                               "belong to another system")
    raw = row.get("size")
    if raw is None:
        return ("unknown", 0, "no size field, so this file cannot be measured")
    try:
        size = int(raw)
    except (TypeError, ValueError):
        return ("unknown", 0, "size is not a number, so this file cannot be measured")
    if size <= 0:
        return ("empty", size, "registered with zero bytes. That is the transfer step "
                               "failing rather than a size limit, and it is a "
                               "different note")
    if size > ceiling:
        return ("over-ceiling", size, "%s, past the %s per-file ceiling. Slack refuses "
                                      "this outright" % (human(size), human(ceiling)))
    if size >= ceiling * near:
        return ("no-headroom", size, "%s, %.1f%% of the %s per-file ceiling. The next "
                                     "growth crosses it"
                                     % (human(size), 100.0 * size / ceiling,
                                        human(ceiling)))
    if size >= transfer:
        return ("transfer-band", size, "%s, above the band where the plain byte "
                                       "transfer starts to time out" % human(size))
    return ("fine", size, "%s, comfortably inside every limit" % human(size))


def size_profile(files, ceiling=CEILING, transfer=TRANSFER_BAND, near=NEAR):
    """The distribution, because one file's size is not a finding. Pure.

    Returns (counts, biggest, percent) where counts maps band name to a count,
    biggest is (file_id, name, size) or None, and percent is the biggest file
    as a percentage of the ceiling. That last number is the whole report: it
    says how much of the runway is left, which a list of failures does not.
    """
    counts, biggest = {}, None
    for f in files or []:
        name, size, _detail = band(f, ceiling, transfer, near)
        counts[name] = counts.get(name, 0) + 1
        if name in ("external", "unknown"):
            continue
        if biggest is None or size > biggest[2]:
            biggest = ((f or {}).get("id") or "?",
                       (f or {}).get("name") or (f or {}).get("title") or "?", size)
    percent = 0.0 if not biggest or not ceiling else round(
        100.0 * biggest[2] / ceiling, 1)
    return (counts, biggest, percent)


def timeout_budget(size, mbps, timeout_s):
    """How long does the byte step need, against the timeout you gave it? Pure.

    Returns (seconds, verdict, detail). impossible is the interesting verdict:
    it means the transfer could not have finished on a completely healthy link,
    so the failure is a number in your own configuration rather than anything
    about Slack, the network or the file.
    """
    try:
        n = float(size)
        rate = float(mbps)
        budget = float(timeout_s)
    except (TypeError, ValueError):
        return (0.0, "unknown", "a size, a link speed and a timeout are all needed")
    if n <= 0 or rate <= 0 or budget <= 0:
        return (0.0, "unknown", "a size, a link speed and a timeout are all needed")
    seconds = round(n * 8.0 / (rate * 1000000.0), 1)
    if seconds > budget:
        return (seconds, "impossible", "%s needs %.1fs at %g Mbps and the client gives "
                                       "up after %gs, so this upload cannot finish on "
                                       "a healthy link" % (human(n), seconds, rate,
                                                           budget))
    if seconds > budget / 2.0:
        return (seconds, "tight", "%s needs %.1fs at %g Mbps against a %gs timeout. A "
                                  "slow morning is enough to lose it"
                                  % (human(n), seconds, rate, budget))
    return (seconds, "comfortable", "%s needs %.1fs at %g Mbps against a %gs timeout"
                                    % (human(n), seconds, rate, budget))


def refusal_cause(error, size, ceiling=CEILING, transfer=TRANSFER_BAND):
    """Which limit did a failure you already recorded actually hit? Pure.

    Returns (cause, detail). file_too_large is the reason this function exists:
    over the cap it is about the file, and well under it, it is about the
    workspace's aggregate storage quota. Same string, unrelated repairs.
    """
    err = str(error or "").strip().lower()
    try:
        n = int(size)
    except (TypeError, ValueError):
        n = 0
    if err in ("file_too_large", "too_large", "request_entity_too_large"):
        if n and n > ceiling:
            return ("ceiling", "%s is past the %s per-file cap. Split it, compress it, "
                               "or put it somewhere that is not Slack"
                               % (human(n), human(ceiling)))
        if n:
            return ("workspace-quota", "%s is far under the %s cap, so the refusal is "
                                       "about the workspace's aggregate storage rather "
                                       "than this file" % (human(n), human(ceiling)))
        return ("ceiling-or-quota", "file_too_large with no size recorded. Record the "
                                    "byte count and this becomes decidable")
    if err in ("", "none", "timeout", "timed_out", "read_timeout", "connection_error"):
        if n >= transfer:
            return ("transfer", "no Slack error at all: the byte step is a plain HTTP "
                                "request to a storage host and it ran out of time. "
                                "Raise that client's timeout, not the retry count")
        return ("not-a-size-problem", "a transport failure on a small file, which is "
                                      "the network rather than any Slack limit")
    if err == "internal_error" and n >= transfer:
        return ("large-internal-error", "internal_error on %s. On a large upload this "
                                        "is usually the size wearing a different "
                                        "costume; treat it as the transfer" % human(n))
    if err in ("invalid_arguments", "invalid_length"):
        return ("declared-length", "the declared length and the bytes disagreed. That "
                                   "is the upload sequence rather than a size limit")
    return ("not-a-size-problem", "%s is not one of the size errors; read it on its "
                                  "own terms" % (err or "an empty error string"))


def page_files(session, user, page_size, max_pages):
    """Page files.list. A read, and the only paginated call here."""
    out, page, pages = [], 1, 1
    while page <= min(pages, max_pages):
        params = {"count": str(page_size), "types": "all", "page": str(page)}
        if user:
            params["user"] = user
        body = session.get(API + "files.list", params=params, timeout=30).json()
        if body.get("ok") is not True:
            log.error("files.list unavailable    %s", body.get("error"))
            return out, pages
        out.extend(body.get("files") or [])
        pages = int((body.get("paging") or {}).get("pages") or 1)
        page += 1
    return out, pages


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--token-env", default="SLACK_BOT_TOKEN",
                    help="environment variable holding the bot token")
    ap.add_argument("--user", default="", help="owner to audit; defaults to this token")
    ap.add_argument("--all-users", action="store_true",
                    help="measure every file in the workspace, not just the app's")
    ap.add_argument("--transfer-mb", type=float, default=TRANSFER_BAND / 1048576.0,
                    help="size above which your own transfers get slow")
    ap.add_argument("--near", type=float, default=NEAR,
                    help="fraction of the ceiling that counts as no headroom")
    ap.add_argument("--link-mbps", type=float, default=0.0,
                    help="uplink speed, for the transfer arithmetic")
    ap.add_argument("--client-timeout", type=float, default=0.0,
                    help="the timeout your HTTP client uses for the byte step")
    ap.add_argument("--failed-error", default="",
                    help="an error string your logs recorded for a failed upload")
    ap.add_argument("--failed-size", type=int, default=0,
                    help="the byte count of that failed upload")
    ap.add_argument("--page-size", type=int, default=200)
    ap.add_argument("--max-pages", type=int, default=25)
    args = ap.parse_args()

    token = os.environ.get(args.token_env)
    if not token:
        log.error("set %s to a bot token with files:read", args.token_env)
        return 2
    transfer = int(args.transfer_mb * 1048576)

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + token})
    who_resp = s.get(API + "auth.test", timeout=30)
    who = who_resp.json()
    if who.get("ok") is not True:
        log.error("auth.test  unavailable    %s", who.get("error"))
        return 2
    log.info("identity   %s (%s) in %s", who.get("user_id"), who.get("user"),
             who.get("team"))
    scopes = who_resp.headers.get("x-oauth-scopes") or ""
    if scopes and "files:read" not in scopes.split(","):
        log.warning("scope      files:read is not granted; files.list will refuse")

    owner = "" if args.all_users else (args.user or who.get("user_id") or "")
    files, pages = page_files(s, owner, args.page_size, args.max_pages)
    log.info("files      %d file(s) owned by %s, over %d page(s)",
             len(files), owner or "anyone", pages)

    flagged = 0
    for f in files:
        name, _size, detail = band(f, CEILING, transfer, args.near)
        if name not in FINDINGS:
            continue
        flagged += 1
        log.warning("band       %-14s %s %s  %s", name, f.get("id") or "?",
                    f.get("name") or "?", detail)

    counts, biggest, percent = size_profile(files, CEILING, transfer, args.near)
    if biggest:
        log.info("profile    biggest %s (%.1f%% of the ceiling); %d file(s) in the "
                 "transfer band", human(biggest[2]), percent,
                 counts.get("transfer-band", 0))
    if counts.get("empty"):
        log.info("handoff    %d file(s) registered with zero bytes: a stalled upload "
                 "sequence rather than a size limit", counts["empty"])

    if biggest and args.link_mbps and args.client_timeout:
        _sec, verdict, detail = timeout_budget(biggest[2], args.link_mbps,
                                               args.client_timeout)
        (log.warning if verdict == "impossible" else log.info)(
            "budget     %-14s %s", verdict, detail)

    if args.failed_error or args.failed_size:
        cause, detail = refusal_cause(args.failed_error, args.failed_size, CEILING,
                                      transfer)
        log.warning("cause      %-14s %s", cause, detail)

    if not flagged:
        log.info("verdict    clear          nothing this app owns is near a limit")
        return 0
    log.warning("verdict    %d of %d file(s) are at or near a limit", flagged,
                len(files))
    log.warning("  repair: raise the timeout on the byte step; it is a plain HTTP "
                "request to a storage host and does not use your Slack client's")
    log.warning("  repair: put the large artifacts in object storage and post a link "
                "into the channel, so Slack carries the notification not the payload")
    log.warning("  repair: if the error was file_too_large on a small file, the "
                "workspace storage quota is full and no code change will help")
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Measure how close your uploads are to the ceiling that will stop them.
 *
 * Read only. files.list, auth.test and team.info are reads. Nothing here mints
 * an upload URL, sends a byte anywhere, deletes a file or fetches a
 * url_private: a bot token with files:read is enough.
 *
 * Slack caps one file at 1 GB and that is almost never the number you meet.
 * The byte transfer goes to a storage host that is not a Slack API host, over a
 * plain HTTP request that inherits none of your Slack client's configuration,
 * and it is the step that gives up first.
 */

const API = 'https://slack.com/api/';

/** The documented per-file ceiling: one gibibyte. */
export const CEILING = 1024 ** 3;
/** Where the plain byte transfer starts being the problem instead of the size. */
export const TRANSFER_BAND = 25 * 1024 * 1024;
/** What counts as no room left: a file this close crosses the cap on growth. */
export const NEAR = 0.75;
/** The bands worth waking somebody for. */
export const FINDINGS = ['over-ceiling', 'no-headroom', 'transfer-band'];

/** Bytes as something a person can read. Pure. */
export function human(size) {
  let n = Number(size);
  if (!Number.isFinite(n)) return '?';
  for (const unit of ['B', 'KB', 'MB', 'GB']) {
    if (Math.abs(n) < 1024 || unit === 'GB') return `${n.toFixed(1)} ${unit}`;
    n /= 1024;
  }
  return `${n.toFixed(1)} GB`;
}

/**
 * Which size band is one file in? Pure. Returns [band, size, detail].
 *
 * The bands are not "ok" and "too big". A file at 79% of the ceiling is a
 * scheduled failure, and a file in the transfer band fails on a slow morning.
 * A zero-byte file is classified and handed off: that is a stalled upload
 * sequence rather than a size, and it wants the opposite repair.
 */
export function band(f, ceiling = CEILING, transfer = TRANSFER_BAND, near = NEAR) {
  const row = f ?? {};
  if (row.is_external) {
    return ['external', 0, 'hosted outside Slack, so the bytes and their limits belong '
      + 'to another system'];
  }
  if (row.size === undefined || row.size === null) {
    return ['unknown', 0, 'no size field, so this file cannot be measured'];
  }
  const size = Number.parseInt(row.size, 10);
  if (!Number.isFinite(size)) {
    return ['unknown', 0, 'size is not a number, so this file cannot be measured'];
  }
  if (size <= 0) {
    return ['empty', size, 'registered with zero bytes. That is the transfer step '
      + 'failing rather than a size limit, and it is a different note'];
  }
  if (size > ceiling) {
    return ['over-ceiling', size, `${human(size)}, past the ${human(ceiling)} per-file `
      + 'ceiling. Slack refuses this outright'];
  }
  if (size >= ceiling * near) {
    const pct = ((100 * size) / ceiling).toFixed(1);
    return ['no-headroom', size, `${human(size)}, ${pct}% of the ${human(ceiling)} `
      + 'per-file ceiling. The next growth crosses it'];
  }
  if (size >= transfer) {
    return ['transfer-band', size, `${human(size)}, above the band where the plain byte `
      + 'transfer starts to time out'];
  }
  return ['fine', size, `${human(size)}, comfortably inside every limit`];
}

/**
 * The distribution, because one file's size is not a finding. Pure.
 * Returns [counts, biggest, percent]; percent is the runway that is left.
 */
export function sizeProfile(files, ceiling = CEILING, transfer = TRANSFER_BAND,
  near = NEAR) {
  const counts = {};
  let biggest = null;
  for (const f of files ?? []) {
    const [name, size] = band(f, ceiling, transfer, near);
    counts[name] = (counts[name] ?? 0) + 1;
    if (name === 'external' || name === 'unknown') continue;
    if (biggest === null || size > biggest[2]) {
      biggest = [(f ?? {}).id ?? '?', (f ?? {}).name ?? (f ?? {}).title ?? '?', size];
    }
  }
  const percent = !biggest || !ceiling
    ? 0 : Math.round((1000 * biggest[2]) / ceiling) / 10;
  return [counts, biggest, percent];
}

/**
 * How long does the byte step need, against the timeout you gave it? Pure.
 * Returns [seconds, verdict, detail]; impossible means the budget never
 * balanced, which is a number in your own configuration rather than a network.
 */
export function timeoutBudget(size, mbps, timeoutS) {
  const n = Number(size);
  const rate = Number(mbps);
  const budget = Number(timeoutS);
  if (![n, rate, budget].every(Number.isFinite) || n <= 0 || rate <= 0 || budget <= 0) {
    return [0, 'unknown', 'a size, a link speed and a timeout are all needed'];
  }
  const seconds = Math.round((n * 8 * 10) / (rate * 1000000)) / 10;
  if (seconds > budget) {
    return [seconds, 'impossible', `${human(n)} needs ${seconds.toFixed(1)}s at `
      + `${rate} Mbps and the client gives up after ${budget}s, so this upload cannot `
      + 'finish on a healthy link'];
  }
  if (seconds > budget / 2) {
    return [seconds, 'tight', `${human(n)} needs ${seconds.toFixed(1)}s at ${rate} Mbps `
      + `against a ${budget}s timeout. A slow morning is enough to lose it`];
  }
  return [seconds, 'comfortable', `${human(n)} needs ${seconds.toFixed(1)}s at `
    + `${rate} Mbps against a ${budget}s timeout`];
}

/**
 * Which limit did a failure you already recorded actually hit? Pure.
 * file_too_large is the reason this exists: over the cap it is about the file,
 * well under it, it is about the workspace's aggregate storage quota.
 */
export function refusalCause(error, size, ceiling = CEILING,
  transfer = TRANSFER_BAND) {
  const err = String(error ?? '').trim().toLowerCase();
  const n = Number.parseInt(size, 10) || 0;
  if (['file_too_large', 'too_large', 'request_entity_too_large'].includes(err)) {
    if (n && n > ceiling) {
      return ['ceiling', `${human(n)} is past the ${human(ceiling)} per-file cap. Split `
        + 'it, compress it, or put it somewhere that is not Slack'];
    }
    if (n) {
      return ['workspace-quota', `${human(n)} is far under the ${human(ceiling)} cap, `
        + 'so the refusal is about the workspace aggregate storage rather than this '
        + 'file'];
    }
    return ['ceiling-or-quota', 'file_too_large with no size recorded. Record the byte '
      + 'count and this becomes decidable'];
  }
  if (['', 'none', 'timeout', 'timed_out', 'read_timeout', 'connection_error']
    .includes(err)) {
    if (n >= transfer) {
      return ['transfer', 'no Slack error at all: the byte step is a plain HTTP request '
        + 'to a storage host and it ran out of time. Raise that client timeout, not '
        + 'the retry count'];
    }
    return ['not-a-size-problem', 'a transport failure on a small file, which is the '
      + 'network rather than any Slack limit'];
  }
  if (err === 'internal_error' && n >= transfer) {
    return ['large-internal-error', `internal_error on ${human(n)}. On a large upload `
      + 'this is usually the size wearing a different costume; treat it as the '
      + 'transfer'];
  }
  if (['invalid_arguments', 'invalid_length'].includes(err)) {
    return ['declared-length', 'the declared length and the bytes disagreed. That is '
      + 'the upload sequence rather than a size limit'];
  }
  return ['not-a-size-problem', `${err || 'an empty error string'} is not one of the `
    + 'size errors; read it on its own terms'];
}

function arg(args, name, fallback = null) {
  const i = args.indexOf(name);
  return i === -1 ? fallback : args[i + 1];
}

async function pageFiles(headers, user, pageSize, maxPages) {
  const files = [];
  let page = 1;
  let pages = 1;
  while (page <= Math.min(pages, maxPages)) {
    const params = new URLSearchParams({
      count: String(pageSize), types: 'all', page: String(page),
    });
    if (user) params.set('user', user);
    const body = await (await fetch(`${API}files.list?${params}`, { headers })).json();
    if (body.ok !== true) {
      console.error(`files.list unavailable    ${body.error}`);
      return [files, pages];
    }
    files.push(...(body.files ?? []));
    pages = Number((body.paging ?? {}).pages ?? 1) || 1;
    page += 1;
  }
  return [files, pages];
}

async function main() {
  const args = process.argv.slice(2);
  const tokenEnv = arg(args, '--token-env', 'SLACK_BOT_TOKEN');
  const token = process.env[tokenEnv];
  if (!token) {
    console.error(`set ${tokenEnv} to a bot token with files:read`);
    process.exitCode = 2;
    return;
  }
  const transfer = Math.round(Number(arg(args, '--transfer-mb',
    TRANSFER_BAND / 1048576)) * 1048576);
  const near = Number(arg(args, '--near', NEAR));
  const mbps = Number(arg(args, '--link-mbps', 0));
  const clientTimeout = Number(arg(args, '--client-timeout', 0));

  const headers = { Authorization: `Bearer ${token}` };
  const whoResp = await fetch(`${API}auth.test`, { headers });
  const who = await whoResp.json();
  if (who.ok !== true) {
    console.error(`auth.test  unavailable    ${who.error}`);
    process.exitCode = 2;
    return;
  }
  console.log(`identity   ${who.user_id} (${who.user}) in ${who.team}`);
  const scopes = whoResp.headers.get('x-oauth-scopes') ?? '';
  if (scopes && !scopes.split(',').includes('files:read')) {
    console.warn('scope      files:read is not granted; files.list will refuse');
  }

  const owner = args.includes('--all-users') ? '' : (arg(args, '--user', '')
    || who.user_id || '');
  const [files, pages] = await pageFiles(headers, owner,
    Number(arg(args, '--page-size', 200)), Number(arg(args, '--max-pages', 25)));
  console.log(`files      ${files.length} file(s) owned by ${owner || 'anyone'}, over `
    + `${pages} page(s)`);

  let flagged = 0;
  for (const f of files) {
    const [name, , detail] = band(f, CEILING, transfer, near);
    if (!FINDINGS.includes(name)) continue;
    flagged += 1;
    console.warn(`band       ${name.padEnd(14)} ${f.id ?? '?'} ${f.name ?? '?'}  `
      + `${detail}`);
  }

  const [counts, biggest, percent] = sizeProfile(files, CEILING, transfer, near);
  if (biggest) {
    console.log(`profile    biggest ${human(biggest[2])} (${percent}% of the ceiling); `
      + `${counts['transfer-band'] ?? 0} file(s) in the transfer band`);
  }
  if (counts.empty) {
    console.log(`handoff    ${counts.empty} file(s) registered with zero bytes: a `
      + 'stalled upload sequence rather than a size limit');
  }
  if (biggest && mbps && clientTimeout) {
    const [, verdict, detail] = timeoutBudget(biggest[2], mbps, clientTimeout);
    const line = `budget     ${verdict.padEnd(14)} ${detail}`;
    if (verdict === 'impossible') console.warn(line); else console.log(line);
  }
  const failedError = arg(args, '--failed-error', '');
  const failedSize = Number(arg(args, '--failed-size', 0));
  if (failedError || failedSize) {
    const [cause, detail] = refusalCause(failedError, failedSize, CEILING, transfer);
    console.warn(`cause      ${cause.padEnd(14)} ${detail}`);
  }

  if (!flagged) {
    console.log('verdict    clear          nothing this app owns is near a limit');
    return;
  }
  console.warn(`verdict    ${flagged} of ${files.length} file(s) are at or near a limit`);
  console.warn('  repair: raise the timeout on the byte step; it is a plain HTTP '
    + 'request to a storage host and does not use your Slack client configuration');
  console.warn('  repair: put the large artifacts in object storage and post a link '
    + 'into the channel, so Slack carries the notification and not the payload');
  process.exitCode = 1;
}

// Only run when invoked directly, so importing this module in the tests does
// not execute main() and fail the file on a missing token.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from slack_file_sizes import band, refusal_cause, size_profile, timeout_budget

MB = 1024 * 1024
GB = 1024 * MB


def test_a_small_file_is_inside_every_limit():
    name, size, _detail = band({"id": "F1", "size": 4 * MB})
    assert name == "fine"
    assert size == 4 * MB


def test_a_file_in_the_transfer_band_is_flagged_below_the_cap():
    name, _size, detail = band({"id": "F1", "size": 61 * MB})
    assert name == "transfer-band"
    assert "time out" in detail


def test_the_band_edge_is_an_argument_not_a_constant():
    assert band({"size": 61 * MB}, transfer=200 * MB)[0] == "fine"


def test_three_quarters_of_the_ceiling_is_a_scheduled_failure():
    name, _size, detail = band({"id": "F1", "size": 812 * MB})
    assert name == "no-headroom"
    assert "79.3%" in detail


def test_past_the_ceiling_is_refused_outright():
    assert band({"size": GB + 1})[0] == "over-ceiling"


def test_zero_bytes_is_handed_off_rather_than_called_small():
    name, _size, detail = band({"id": "F1", "size": 0})
    assert name == "empty"
    assert "different note" in detail


def test_an_external_file_is_not_measured_against_slack_limits():
    assert band({"is_external": True, "size": 9 * GB})[0] == "external"


def test_a_file_with_no_size_field_is_unknown_rather_than_zero():
    assert band({"id": "F1"})[0] == "unknown"
    assert band({"id": "F1", "size": "big"})[0] == "unknown"


def test_the_profile_reports_the_biggest_as_a_fraction_of_the_ceiling():
    counts, biggest, percent = size_profile([
        {"id": "F1", "name": "a.csv", "size": 4 * MB},
        {"id": "F2", "name": "b.zip", "size": 812 * MB},
    ])
    assert counts == {"fine": 1, "no-headroom": 1}
    assert biggest == ("F2", "b.zip", 812 * MB)
    assert percent == 79.3


def test_external_and_unmeasurable_files_cannot_become_the_biggest():
    _counts, biggest, _percent = size_profile([
        {"id": "F1", "size": 4 * MB},
        {"id": "F2", "is_external": True, "size": 9 * GB},
    ])
    assert biggest[0] == "F1"


def test_an_empty_run_reports_no_biggest_rather_than_dividing():
    assert size_profile([]) == ({}, None, 0.0)


def test_a_transfer_that_needs_longer_than_the_timeout_is_impossible():
    seconds, verdict, detail = timeout_budget(812 * MB, 40, 30)
    assert verdict == "impossible"
    assert seconds == 170.3
    assert "healthy link" in detail


def test_a_transfer_using_most_of_the_budget_is_tight():
    assert timeout_budget(60 * MB, 40, 20)[1] == "tight"


def test_a_small_transfer_is_comfortable():
    assert timeout_budget(4 * MB, 40, 30)[1] == "comfortable"


def test_the_budget_needs_all_three_numbers():
    assert timeout_budget(4 * MB, 0, 30)[1] == "unknown"
    assert timeout_budget(None, 40, 30)[1] == "unknown"


def test_file_too_large_over_the_cap_is_about_the_file():
    cause, _detail = refusal_cause("file_too_large", GB + 1)
    assert cause == "ceiling"


def test_file_too_large_on_a_small_file_is_about_the_workspace():
    cause, detail = refusal_cause("file_too_large", 4 * MB)
    assert cause == "workspace-quota"
    assert "aggregate storage" in detail


def test_no_error_at_all_on_a_large_file_is_the_byte_transfer():
    cause, detail = refusal_cause("", 300 * MB)
    assert cause == "transfer"
    assert "timeout" in detail


def test_internal_error_on_a_large_upload_is_read_as_the_transfer():
    assert refusal_cause("internal_error", 300 * MB)[0] == "large-internal-error"


def test_a_length_complaint_belongs_to_the_upload_sequence_note():
    assert refusal_cause("invalid_arguments", 4 * MB)[0] == "declared-length"


def test_an_unrelated_error_is_not_dressed_up_as_a_size_problem():
    assert refusal_cause("not_in_channel", 4 * MB)[0] == "not-a-size-problem"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  band, refusalCause, sizeProfile, timeoutBudget,
} from './slack-file-sizes.mjs';

const MB = 1024 * 1024;
const GB = 1024 * MB;

test('a small file is inside every limit', () => {
  const [name, size] = band({ id: 'F1', size: 4 * MB });
  assert.equal(name, 'fine');
  assert.equal(size, 4 * MB);
});

test('a file in the transfer band is flagged below the cap', () => {
  const [name, , detail] = band({ id: 'F1', size: 61 * MB });
  assert.equal(name, 'transfer-band');
  assert.match(detail, /time out/);
});

test('the band edge is an argument not a constant', () => {
  assert.equal(band({ size: 61 * MB }, GB, 200 * MB)[0], 'fine');
});

test('three quarters of the ceiling is a scheduled failure', () => {
  const [name, , detail] = band({ id: 'F1', size: 812 * MB });
  assert.equal(name, 'no-headroom');
  assert.match(detail, /79\.3%/);
});

test('past the ceiling is refused outright', () => {
  assert.equal(band({ size: GB + 1 })[0], 'over-ceiling');
});

test('zero bytes is handed off rather than called small', () => {
  const [name, , detail] = band({ id: 'F1', size: 0 });
  assert.equal(name, 'empty');
  assert.match(detail, /different note/);
});

test('an external file is not measured against Slack limits', () => {
  assert.equal(band({ is_external: true, size: 9 * GB })[0], 'external');
});

test('a file with no size field is unknown rather than zero', () => {
  assert.equal(band({ id: 'F1' })[0], 'unknown');
  assert.equal(band({ id: 'F1', size: 'big' })[0], 'unknown');
});

test('the profile reports the biggest as a fraction of the ceiling', () => {
  const [counts, biggest, percent] = sizeProfile([
    { id: 'F1', name: 'a.csv', size: 4 * MB },
    { id: 'F2', name: 'b.zip', size: 812 * MB },
  ]);
  assert.deepEqual(counts, { fine: 1, 'no-headroom': 1 });
  assert.deepEqual(biggest, ['F2', 'b.zip', 812 * MB]);
  assert.equal(percent, 79.3);
});

test('external and unmeasurable files cannot become the biggest', () => {
  const [, biggest] = sizeProfile([
    { id: 'F1', size: 4 * MB },
    { id: 'F2', is_external: true, size: 9 * GB },
  ]);
  assert.equal(biggest[0], 'F1');
});

test('an empty run reports no biggest rather than dividing', () => {
  assert.deepEqual(sizeProfile([]), [{}, null, 0]);
});

test('a transfer that needs longer than the timeout is impossible', () => {
  const [seconds, verdict, detail] = timeoutBudget(812 * MB, 40, 30);
  assert.equal(verdict, 'impossible');
  assert.equal(seconds, 170.3);
  assert.match(detail, /healthy link/);
});

test('a transfer using most of the budget is tight', () => {
  assert.equal(timeoutBudget(60 * MB, 40, 20)[1], 'tight');
});

test('a small transfer is comfortable', () => {
  assert.equal(timeoutBudget(4 * MB, 40, 30)[1], 'comfortable');
});

test('the budget needs all three numbers', () => {
  assert.equal(timeoutBudget(4 * MB, 0, 30)[1], 'unknown');
  assert.equal(timeoutBudget(null, 40, 30)[1], 'unknown');
});

test('file_too_large over the cap is about the file', () => {
  assert.equal(refusalCause('file_too_large', GB + 1)[0], 'ceiling');
});

test('file_too_large on a small file is about the workspace', () => {
  const [cause, detail] = refusalCause('file_too_large', 4 * MB);
  assert.equal(cause, 'workspace-quota');
  assert.match(detail, /aggregate storage/);
});

test('no error at all on a large file is the byte transfer', () => {
  const [cause, detail] = refusalCause('', 300 * MB);
  assert.equal(cause, 'transfer');
  assert.match(detail, /timeout/);
});

test('internal_error on a large upload is read as the transfer', () => {
  assert.equal(refusalCause('internal_error', 300 * MB)[0], 'large-internal-error');
});

test('a length complaint belongs to the upload sequence note', () => {
  assert.equal(refusalCause('invalid_arguments', 4 * MB)[0], 'declared-length');
});

test('an unrelated error is not dressed up as a size problem', () => {
  assert.equal(refusalCause('not_in_channel', 4 * MB)[0], 'not-a-size-problem');
});