| @@ -0,0 +1,368 @@ |
| 1 | +//! `downloadFile` and `saveFile` on Android. |
| 2 | +//! |
| 3 | +//! Neither needs the main thread, a listener, or an Activity result — the |
| 4 | +//! download is queued with the system's own manager and the save is ordinary |
| 5 | +//! file I/O — so both are served whole rather than in halves. |
| 6 | +//! |
| 7 | +//! ## saveFile can report a path it never wrote |
| 8 | +//! |
| 9 | +//! The shim's data-URL branch is: |
| 10 | +//! |
| 11 | +//! ```kotlin |
| 12 | +//! if (data.startsWith("data:")) { |
| 13 | +//! val parts = data.split(",") |
| 14 | +//! if (parts.size == 2) { ...decode and write... } |
| 15 | +//! } else { |
| 16 | +//! file.writeText(data) |
| 17 | +//! } |
| 18 | +//! ...resolve(file.absolutePath) |
| 19 | +//! ``` |
| 20 | +//! |
| 21 | +//! `split(",")` splits on *every* comma, so a data URL whose payload contains |
| 22 | +//! one — base64 does not produce commas, but `data:text/plain,a,b` is a legal |
| 23 | +//! data URL — yields three parts, the `if` is skipped, **nothing is written**, |
| 24 | +//! and the resolve still hands the page a path. The file may not exist at all. |
| 25 | +//! |
| 26 | +//! Reproduced rather than corrected, because the reply is what a page acts on |
| 27 | +//! and changing it is a behaviour change. Recorded as `Plan.nothing` so the |
| 28 | +//! case has a name instead of being an absent `else`. See #175. |
| 29 | +//! |
| 30 | +//! ## The decoding is Java's |
| 31 | +//! |
| 32 | +//! `android.util.Base64.decode` rather than a decoder here, for the reason |
| 33 | +//! `bridge_android_notifications` hashes ids in Java: what matters is not |
| 34 | +//! decoding base64 but decoding it the way the shim does, including which |
| 35 | +//! inputs it throws on. A Zig decoder would be a second implementation whose |
| 36 | +//! disagreements only ever show up on a device. |
| 37 | + |
| 38 | +const std = ; |
| 39 | +const jni = ; |
| 40 | +const bridge_error = ; |
| 41 | + |
| 42 | +const Jni = jni.Jni; |
| 43 | +const jobject = jni.jobject; |
| 44 | + |
| 45 | +pub const A = struct { |
| 46 | + pub const download_file = "downloadFile"; |
| 47 | + pub const save_file = "saveFile"; |
| 48 | +}; |
| 49 | + |
| 50 | +pub const download_resolve_global = "_craftDownloadResolve"; |
| 51 | +pub const download_reject_global = "_craftDownloadReject"; |
| 52 | +pub const save_resolve_global = "_craftSaveResolve"; |
| 53 | +pub const save_reject_global = "_craftSaveReject"; |
| 54 | + |
| 55 | +/// What the shim's notification says while a download runs. |
| 56 | +const download_description = "Downloading..."; |
| 57 | + |
| 58 | +/// What `saveFile` will do with the data it was given. |
| 59 | +pub const Plan = union(enum) { |
| 60 | + /// `file.writeText(data)` — anything not starting with `data:`. |
| 61 | + text: []const u8, |
| 62 | + /// `Base64.decode(parts[1])` — a data URL with exactly one comma. |
| 63 | + base64: []const u8, |
| 64 | + /// A data URL with any other number of commas. The shim writes nothing |
| 65 | + /// and resolves with the path anyway. |
| 66 | + nothing, |
| 67 | +}; |
| 68 | + |
| 69 | +/// The shim's branch, comma counting included. |
| 70 | +pub fn planFor(data: []const u8) Plan { |
| 71 | + if (!std.mem.startsWith(u8, data, "data:")) return .{ .text = data }; |
| 72 | + |
| 73 | + // `split(",")` gives `count + 1` parts, so "exactly one comma" is the |
| 74 | + // whole of `parts.size == 2`. |
| 75 | + const first = std.mem.indexOfScalar(u8, data, ',') orelse return .nothing; |
| 76 | + if (std.mem.indexOfScalarPos(u8, data, first + 1, ',') != null) return .nothing; |
| 77 | + |
| 78 | + return .{ .base64 = data[first + 1 ..] }; |
| 79 | +} |
| 80 | + |
| 81 | +/// `downloadManager.enqueue(request)`, and the id it returns. |
| 82 | +pub fn download( |
| 83 | + j: Jni, |
| 84 | + allocator: std.mem.Allocator, |
| 85 | + activity: jobject, |
| 86 | + url: []const u8, |
| 87 | + filename: []const u8, |
| 88 | +) !i64 { |
| 89 | + try j.pushLocalFrame(32); |
| 90 | + defer _ = j.popLocalFrame(null); |
| 91 | + |
| 92 | + const uri_cls = try j.findClass("android/net/Uri"); |
| 93 | + const uri = try j.callStaticObjectMethodA( |
| 94 | + uri_cls, |
| 95 | + try j.staticMethodId(uri_cls, "parse", "(Ljava/lang/String;)Landroid/net/Uri;"), |
| 96 | + &.{.{ .l = try j.newStringUtf8(allocator, url) }}, |
| 97 | + ); |
| 98 | + |
| 99 | + const request_cls = try j.findClass("android/app/DownloadManager$Request"); |
| 100 | + const request = try j.newObjectA( |
| 101 | + request_cls, |
| 102 | + try j.methodId(request_cls, "<init>", "(Landroid/net/Uri;)V"), |
| 103 | + &.{.{ .l = uri }}, |
| 104 | + ); |
| 105 | + |
| 106 | + _ = try j.callObjectMethodA( |
| 107 | + request, |
| 108 | + try j.methodId( |
| 109 | + request_cls, |
| 110 | + "setTitle", |
| 111 | + "(Ljava/lang/CharSequence;)Landroid/app/DownloadManager$Request;", |
| 112 | + ), |
| 113 | + &.{.{ .l = try j.newStringUtf8(allocator, filename) }}, |
| 114 | + ); |
| 115 | + |
| 116 | + _ = try j.callObjectMethodA( |
| 117 | + request, |
| 118 | + try j.methodId( |
| 119 | + request_cls, |
| 120 | + "setDescription", |
| 121 | + "(Ljava/lang/CharSequence;)Landroid/app/DownloadManager$Request;", |
| 122 | + ), |
| 123 | + &.{.{ .l = try j.newStringUtf(download_description) }}, |
| 124 | + ); |
| 125 | + |
| 126 | + // Read rather than written down: a wrong visibility does not throw, it |
| 127 | + // just silently stops the user seeing the download. |
| 128 | + const visibility = try j.staticIntField( |
| 129 | + request_cls, |
| 130 | + try j.staticFieldId(request_cls, "VISIBILITY_VISIBLE_NOTIFY_COMPLETED", "I"), |
| 131 | + ); |
| 132 | + _ = try j.callObjectMethodA( |
| 133 | + request, |
| 134 | + try j.methodId(request_cls, "setNotificationVisibility", "(I)Landroid/app/DownloadManager$Request;"), |
| 135 | + &.{.{ .i = visibility }}, |
| 136 | + ); |
| 137 | + |
| 138 | + const environment_cls = try j.findClass("android/os/Environment"); |
| 139 | + const downloads_dir = try j.staticObjectField( |
| 140 | + environment_cls, |
| 141 | + try j.staticFieldId(environment_cls, "DIRECTORY_DOWNLOADS", "Ljava/lang/String;"), |
| 142 | + ); |
| 143 | + _ = try j.callObjectMethodA( |
| 144 | + request, |
| 145 | + try j.methodId( |
| 146 | + request_cls, |
| 147 | + "setDestinationInExternalPublicDir", |
| 148 | + "(Ljava/lang/String;Ljava/lang/String;)Landroid/app/DownloadManager$Request;", |
| 149 | + ), |
| 150 | + &.{ .{ .l = downloads_dir }, .{ .l = try j.newStringUtf8(allocator, filename) } }, |
| 151 | + ); |
| 152 | + |
| 153 | + const context_cls = try j.findClass("android/content/Context"); |
| 154 | + const service_name = try j.staticObjectField( |
| 155 | + context_cls, |
| 156 | + try j.staticFieldId(context_cls, "DOWNLOAD_SERVICE", "Ljava/lang/String;"), |
| 157 | + ); |
| 158 | + const manager = try j.callObjectMethodA( |
| 159 | + activity, |
| 160 | + try j.methodId( |
| 161 | + try j.objectClass(activity), |
| 162 | + "getSystemService", |
| 163 | + "(Ljava/lang/String;)Ljava/lang/Object;", |
| 164 | + ), |
| 165 | + &.{.{ .l = service_name }}, |
| 166 | + ); |
| 167 | + |
| 168 | + return j.callLongMethodA( |
| 169 | + manager, |
| 170 | + try j.methodId( |
| 171 | + try j.objectClass(manager), |
| 172 | + "enqueue", |
| 173 | + "(Landroid/app/DownloadManager$Request;)J", |
| 174 | + ), |
| 175 | + &.{.{ .l = request }}, |
| 176 | + ); |
| 177 | +} |
| 178 | + |
| 179 | +/// Write the file and return its absolute path. |
| 180 | +/// |
| 181 | +/// The path is produced whether or not anything was written, because that is |
| 182 | +/// what the shim resolves with — see the note at the top of this file. |
| 183 | +pub fn save( |
| 184 | + j: Jni, |
| 185 | + allocator: std.mem.Allocator, |
| 186 | + activity: jobject, |
| 187 | + filename: []const u8, |
| 188 | + plan: Plan, |
| 189 | +) ![]u8 { |
| 190 | + try j.pushLocalFrame(32); |
| 191 | + defer _ = j.popLocalFrame(null); |
| 192 | + |
| 193 | + const environment_cls = try j.findClass("android/os/Environment"); |
| 194 | + const documents_dir = try j.staticObjectField( |
| 195 | + environment_cls, |
| 196 | + try j.staticFieldId(environment_cls, "DIRECTORY_DOCUMENTS", "Ljava/lang/String;"), |
| 197 | + ); |
| 198 | + const parent = try j.callObjectMethodA( |
| 199 | + activity, |
| 200 | + try j.methodId( |
| 201 | + try j.objectClass(activity), |
| 202 | + "getExternalFilesDir", |
| 203 | + "(Ljava/lang/String;)Ljava/io/File;", |
| 204 | + ), |
| 205 | + &.{.{ .l = documents_dir }}, |
| 206 | + ); |
| 207 | + |
| 208 | + const file_cls = try j.findClass("java/io/File"); |
| 209 | + const file = try j.newObjectA( |
| 210 | + file_cls, |
| 211 | + try j.methodId(file_cls, "<init>", "(Ljava/io/File;Ljava/lang/String;)V"), |
| 212 | + &.{ .{ .l = parent }, .{ .l = try j.newStringUtf8(allocator, filename) } }, |
| 213 | + ); |
| 214 | + |
| 215 | + switch (plan) { |
| 216 | + .nothing => {}, |
| 217 | + .text => |text| try writeBytes(j, file, try utf8Bytes(j, allocator, text)), |
| 218 | + .base64 => |encoded| try writeBytes(j, file, try decodeBase64(j, allocator, encoded)), |
| 219 | + } |
| 220 | + |
| 221 | + const path = try j.callObjectMethod( |
| 222 | + file, |
| 223 | + try j.methodId(file_cls, "getAbsolutePath", "()Ljava/lang/String;"), |
| 224 | + ); |
| 225 | + return j.stringToUtf8(allocator, path); |
| 226 | +} |
| 227 | + |
| 228 | +/// `Base64.decode(encoded, Base64.DEFAULT)`. |
| 229 | +fn decodeBase64(j: Jni, allocator: std.mem.Allocator, encoded: []const u8) !jobject { |
| 230 | + const base64_cls = try j.findClass("android/util/Base64"); |
| 231 | + |
| 232 | + // Read rather than written down: `URL_SAFE` is a different alphabet, and |
| 233 | + // decoding with the wrong one produces bytes rather than an error. |
| 234 | + const default_flags = try j.staticIntField( |
| 235 | + base64_cls, |
| 236 | + try j.staticFieldId(base64_cls, "DEFAULT", "I"), |
| 237 | + ); |
| 238 | + |
| 239 | + return j.callStaticObjectMethodA( |
| 240 | + base64_cls, |
| 241 | + try j.staticMethodId(base64_cls, "decode", "(Ljava/lang/String;I)[B"), |
| 242 | + &.{ .{ .l = try j.newStringUtf8(allocator, encoded) }, .{ .i = default_flags } }, |
| 243 | + ); |
| 244 | +} |
| 245 | + |
| 246 | +/// `text.toByteArray()` — Kotlin's `writeText` uses UTF-8. |
| 247 | +fn utf8Bytes(j: Jni, allocator: std.mem.Allocator, text: []const u8) !jobject { |
| 248 | + const string = try j.newStringUtf8(allocator, text); |
| 249 | + const charset_cls = try j.findClass("java/nio/charset/StandardCharsets"); |
| 250 | + const utf8 = try j.staticObjectField( |
| 251 | + charset_cls, |
| 252 | + try j.staticFieldId(charset_cls, "UTF_8", "Ljava/nio/charset/Charset;"), |
| 253 | + ); |
| 254 | + return j.callObjectMethodA( |
| 255 | + string, |
| 256 | + try j.methodId( |
| 257 | + try j.objectClass(string), |
| 258 | + "getBytes", |
| 259 | + "(Ljava/nio/charset/Charset;)[B", |
| 260 | + ), |
| 261 | + &.{.{ .l = utf8 }}, |
| 262 | + ); |
| 263 | +} |
| 264 | + |
| 265 | +/// `FileOutputStream(file).use { it.write(bytes) }`. |
| 266 | +fn writeBytes(j: Jni, file: jobject, bytes: jobject) !void { |
| 267 | + try j.pushLocalFrame(8); |
| 268 | + defer _ = j.popLocalFrame(null); |
| 269 | + |
| 270 | + const stream_cls = try j.findClass("java/io/FileOutputStream"); |
| 271 | + const stream = try j.newObjectA( |
| 272 | + stream_cls, |
| 273 | + try j.methodId(stream_cls, "<init>", "(Ljava/io/File;)V"), |
| 274 | + &.{.{ .l = file }}, |
| 275 | + ); |
| 276 | + |
| 277 | + // Resolved before the write, so the close below can be a plain `defer`. |
| 278 | + // A stream left open holds its file descriptor until the GC gets to it, |
| 279 | + // which on a device is long enough to matter — so it closes however this |
| 280 | + // leaves, error included. |
| 281 | + const close = try j.methodId(stream_cls, "close", "()V"); |
| 282 | + defer j.callVoidMethodA(stream, close, &.{}) catch {}; |
| 283 | + |
| 284 | + try j.callVoidMethodA( |
| 285 | + stream, |
| 286 | + try j.methodId(stream_cls, "write", "([B)V"), |
| 287 | + &.{.{ .l = bytes }}, |
| 288 | + ); |
| 289 | +} |
| 290 | + |
| 291 | +/// `text` as a JSON string. |
| 292 | +pub fn jsonString(allocator: std.mem.Allocator, text: []const u8) ![]u8 { |
| 293 | + var out: std.ArrayListUnmanaged(u8) = .empty; |
| 294 | + errdefer out.deinit(allocator); |
| 295 | + |
| 296 | + try out.append(allocator, '"'); |
| 297 | + try bridge_error.appendJsonEscaped(allocator, &out, text); |
| 298 | + try out.append(allocator, '"'); |
| 299 | + return out.toOwnedSlice(allocator); |
| 300 | +} |
| 301 | + |
| 302 | +// ============================================================================= |
| 303 | +// Tests |
| 304 | +// ============================================================================= |
| 305 | + |
| 306 | +const testing = std.testing; |
| 307 | + |
| 308 | +test "anything not a data URL is written as text" { |
| 309 | + const plan = planFor("hello, world"); |
| 310 | + try testing.expectEqualStrings("hello, world", plan.text); |
| 311 | + |
| 312 | + // Including text that merely contains "data:" later on. |
| 313 | + try testing.expectEqualStrings("x data:y", planFor("x data:y").text); |
| 314 | + |
| 315 | + // And the empty string, which writes an empty file rather than nothing. |
| 316 | + try testing.expectEqualStrings("", planFor("").text); |
| 317 | +} |
| 318 | + |
| 319 | +test "a data URL with exactly one comma decodes the tail" { |
| 320 | + const plan = planFor("data:image/png;base64,iVBORw0KGgo="); |
| 321 | + try testing.expectEqualStrings("iVBORw0KGgo=", plan.base64); |
| 322 | + |
| 323 | + // The payload can be empty — `Base64.decode("")` is an empty array, so |
| 324 | + // this writes an empty file rather than skipping the write. |
| 325 | + try testing.expectEqualStrings("", planFor("data:,").base64); |
| 326 | +} |
| 327 | + |
| 328 | +test "a data URL with any other number of commas writes nothing at all" { |
| 329 | + // The shim's `if (parts.size == 2)` with no else. The resolve still hands |
| 330 | + // the page `file.absolutePath`, so a page is told where a file is that may |
| 331 | + // not exist. See #175. |
| 332 | + try testing.expectEqual(Plan.nothing, planFor("data:text/plain,a,b")); |
| 333 | + try testing.expectEqual(Plan.nothing, planFor("data:image/png;base64,AAA,BBB")); |
| 334 | + |
| 335 | + // No comma at all is the same skipped branch. |
| 336 | + try testing.expectEqual(Plan.nothing, planFor("data:image/png;base64")); |
| 337 | + try testing.expectEqual(Plan.nothing, planFor("data:")); |
| 338 | +} |
| 339 | + |
| 340 | +test "the prefix test is the shim's startsWith, not a contains" { |
| 341 | + // `data` alone is text; only the colon makes it a URL. |
| 342 | + try testing.expectEqualStrings("data", planFor("data").text); |
| 343 | + try testing.expect(planFor("data:") == .nothing); |
| 344 | + |
| 345 | + // Case matters: `startsWith` is not case-insensitive, so `DATA:` is text |
| 346 | + // and is written verbatim. |
| 347 | + try testing.expectEqualStrings("DATA:x,y", planFor("DATA:x,y").text); |
| 348 | +} |
| 349 | + |
| 350 | +test "the actions and globals match the shim exactly" { |
| 351 | + try testing.expectEqualStrings("downloadFile", A.download_file); |
| 352 | + try testing.expectEqualStrings("saveFile", A.save_file); |
| 353 | + try testing.expectEqualStrings("_craftDownloadResolve", download_resolve_global); |
| 354 | + try testing.expectEqualStrings("_craftDownloadReject", download_reject_global); |
| 355 | + try testing.expectEqualStrings("_craftSaveResolve", save_resolve_global); |
| 356 | + try testing.expectEqualStrings("_craftSaveReject", save_reject_global); |
| 357 | +} |
| 358 | + |
| 359 | +test "a path carrying a quote comes back as JSON" { |
| 360 | + // `file.absolutePath` contains the filename the page chose, so it is page |
| 361 | + // text arriving back through the reply channel. |
| 362 | + const payload = try jsonString(testing.allocator, "/sdcard/it's \"here\".txt"); |
| 363 | + defer testing.allocator.free(payload); |
| 364 | + |
| 365 | + var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, payload, .{}); |
| 366 | + defer parsed.deinit(); |
| 367 | + try testing.expectEqualStrings("/sdcard/it's \"here\".txt", parsed.value.string); |
| 368 | +} |