|
| 1 | +""" |
| 2 | +learning_observer.remote_assets |
| 3 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 4 | +
|
| 5 | +Utilities for downloading and installing prebuilt frontend asset bundles |
| 6 | +(e.g. exported Next.js apps) that are hosted in a GitHub repository. |
| 7 | +
|
| 8 | +Intended use: LO module ``__init__.py`` files call :func:`fetch_module_assets` |
| 9 | +from their startup checks to ensure their bundled frontend is present. |
| 10 | +
|
| 11 | +Typical repository layout assumed by the pointer-file convention:: |
| 12 | +
|
| 13 | + lo_assets/ |
| 14 | + my_module/ |
| 15 | + my_module-current.tar.gz ← plain-text file containing the tarball name |
| 16 | + my_module-v1.2.3.tar.gz ← the actual tarball |
| 17 | +""" |
| 18 | + |
| 19 | +import os |
| 20 | +import shutil |
| 21 | +import sys |
| 22 | +import tarfile |
| 23 | +import tempfile |
| 24 | +import urllib.request |
| 25 | + |
| 26 | +# --------------------------------------------------------------------------- |
| 27 | +# Default repository coordinates |
| 28 | +# --------------------------------------------------------------------------- |
| 29 | + |
| 30 | +_LO_ASSETS_REPO = 'ArgLab/lo_assets' |
| 31 | +_LO_ASSETS_REF = 'main' |
| 32 | + |
| 33 | + |
| 34 | +# --------------------------------------------------------------------------- |
| 35 | +# Interactive / non-interactive prompts |
| 36 | +# --------------------------------------------------------------------------- |
| 37 | + |
| 38 | +def confirm(prompt, default_noninteractive): |
| 39 | + """ |
| 40 | + Ask a yes/no question and return a boolean. |
| 41 | +
|
| 42 | + Resolution order: |
| 43 | + 1. *default_noninteractive* when stdin is not a TTY. |
| 44 | + 2. An interactive prompt otherwise. |
| 45 | +
|
| 46 | + Example usage in a module startup check:: |
| 47 | +
|
| 48 | + should_fetch = confirm( |
| 49 | + prompt='Download missing assets? (y/n) ', |
| 50 | + default_noninteractive=False, |
| 51 | + ) |
| 52 | + """ |
| 53 | + if not sys.stdin.isatty(): |
| 54 | + return default_noninteractive |
| 55 | + |
| 56 | + return input(prompt).strip().lower() in {'y', 'yes'} |
| 57 | + |
| 58 | + |
| 59 | +# --------------------------------------------------------------------------- |
| 60 | +# Low-level network helpers |
| 61 | +# --------------------------------------------------------------------------- |
| 62 | + |
| 63 | +def read_url(url): |
| 64 | + """ |
| 65 | + Fetch *url* and return its contents as a stripped string. |
| 66 | + """ |
| 67 | + with urllib.request.urlopen(url) as response: |
| 68 | + return response.read().decode('utf-8').strip() |
| 69 | + |
| 70 | + |
| 71 | +def download_file(url, destination): |
| 72 | + """ |
| 73 | + Stream *url* to *destination*, avoiding loading the full response into |
| 74 | + memory. |
| 75 | + """ |
| 76 | + with urllib.request.urlopen(url) as response, open(destination, 'wb') as output_file: |
| 77 | + shutil.copyfileobj(response, output_file) |
| 78 | + |
| 79 | + |
| 80 | +# --------------------------------------------------------------------------- |
| 81 | +# Archive helpers |
| 82 | +# --------------------------------------------------------------------------- |
| 83 | + |
| 84 | +def find_nextjs_root(extracted_dir): |
| 85 | + """ |
| 86 | + Walk *extracted_dir* and return the shallowest path that looks like an |
| 87 | + exported Next.js app (contains both ``index.html`` and a ``_next/`` |
| 88 | + directory). |
| 89 | +
|
| 90 | + Raises ``ValueError`` if no such directory is found. |
| 91 | + """ |
| 92 | + candidates = [] |
| 93 | + for root, _, files in os.walk(extracted_dir): |
| 94 | + if 'index.html' in files and os.path.isdir(os.path.join(root, '_next')): |
| 95 | + candidates.append(root) |
| 96 | + |
| 97 | + if not candidates: |
| 98 | + raise ValueError( |
| 99 | + "Could not find an exported Next.js app inside the archive " |
| 100 | + "(expected index.html and _next/ in the same directory)." |
| 101 | + ) |
| 102 | + |
| 103 | + return min(candidates, key=len) |
| 104 | + |
| 105 | + |
| 106 | +def extract_assets_tarball(tar_path, target_dir): |
| 107 | + """ |
| 108 | + Extract the Next.js app bundle at *tar_path* into *target_dir*. |
| 109 | +
|
| 110 | + The archive may contain arbitrary wrapper directories; only the shallowest |
| 111 | + directory that looks like an exported Next.js app is copied to |
| 112 | + *target_dir*. Any pre-existing *target_dir* is removed first. |
| 113 | +
|
| 114 | + Raises ``ValueError`` (from :func:`find_nextjs_root`) if the archive does |
| 115 | + not contain a recognisable Next.js export. |
| 116 | + """ |
| 117 | + with tempfile.TemporaryDirectory() as temp_extract_dir: |
| 118 | + with tarfile.open(tar_path, mode='r:gz') as archive: |
| 119 | + archive.extractall(temp_extract_dir) |
| 120 | + |
| 121 | + source_root = find_nextjs_root(temp_extract_dir) |
| 122 | + |
| 123 | + if os.path.isdir(target_dir): |
| 124 | + shutil.rmtree(target_dir) |
| 125 | + shutil.copytree(source_root, target_dir) |
| 126 | + |
| 127 | + |
| 128 | +# --------------------------------------------------------------------------- |
| 129 | +# High-level fetch interface |
| 130 | +# --------------------------------------------------------------------------- |
| 131 | + |
| 132 | +def fetch_module_assets( |
| 133 | + target_dir, |
| 134 | + pointer_file, |
| 135 | + assets_url=None, |
| 136 | + assets_repo=_LO_ASSETS_REPO, |
| 137 | + assets_ref=_LO_ASSETS_REF, |
| 138 | +): |
| 139 | + """ |
| 140 | + Download and install a prebuilt Next.js asset bundle for an LO module. |
| 141 | +
|
| 142 | + Parameters |
| 143 | + ---------- |
| 144 | + target_dir: |
| 145 | + Local directory where the extracted app should be placed. |
| 146 | + pointer_file: |
| 147 | + Path within *assets_repo* to a plain-text file whose content is the |
| 148 | + filename of the current tarball, e.g. |
| 149 | + ``'wo_portfolio_diff/wo_portfolio_diff-current.tar.gz'``. |
| 150 | + The tarball is assumed to live in the same directory as this file. |
| 151 | + assets_url: |
| 152 | + If supplied, skip pointer-file resolution and download this URL |
| 153 | + directly. Useful for pinning a specific release or local testing. |
| 154 | + assets_repo: |
| 155 | + ``owner/repo`` slug on GitHub. Defaults to the canonical LO assets |
| 156 | + repository. |
| 157 | + assets_ref: |
| 158 | + Branch, tag, or commit SHA to resolve *pointer_file* against. |
| 159 | + Defaults to ``'main'``. |
| 160 | +
|
| 161 | + Raises |
| 162 | + ------ |
| 163 | + urllib.error.URLError |
| 164 | + Network error while resolving the pointer file or downloading. |
| 165 | + ValueError |
| 166 | + The downloaded archive does not contain a recognisable Next.js export. |
| 167 | + OSError |
| 168 | + File-system error while writing or extracting the archive. |
| 169 | + tarfile.TarError |
| 170 | + The downloaded file is not a valid gzipped tar archive. |
| 171 | + """ |
| 172 | + if assets_url is None: |
| 173 | + pointer_url = ( |
| 174 | + f'https://raw.githubusercontent.com/{assets_repo}/{assets_ref}' |
| 175 | + f'/{pointer_file}' |
| 176 | + ) |
| 177 | + resolved_name = read_url(pointer_url) |
| 178 | + pointer_dir = pointer_file.rsplit('/', 1)[0] |
| 179 | + assets_url = ( |
| 180 | + f'https://raw.githubusercontent.com/{assets_repo}/{assets_ref}' |
| 181 | + f'/{pointer_dir}/{resolved_name}' |
| 182 | + ) |
| 183 | + |
| 184 | + with tempfile.NamedTemporaryFile(suffix='.tar.gz', delete=False) as tmp: |
| 185 | + archive_path = tmp.name |
| 186 | + |
| 187 | + try: |
| 188 | + download_file(assets_url, archive_path) |
| 189 | + extract_assets_tarball(archive_path, target_dir) |
| 190 | + finally: |
| 191 | + os.unlink(archive_path) |
0 commit comments