Skip to content

armgit / ente

Public Imported from GitHub
0

💚 End-to-end encrypted cloud for everything.

Prune web comments

Manav Rathic167442c8675
diff --git a/web/apps/albums/src/public-album/upload/components/Upload.tsx b/web/apps/albums/src/public-album/upload/components/Upload.tsx
index 9a0caaedef..e99dba3e36 100644
--- a/web/apps/albums/src/public-album/upload/components/Upload.tsx
+++ b/web/apps/albums/src/public-album/upload/components/Upload.tsx
@@ -47,11 +47,6 @@ import { t } from "i18next";
import React, { useCallback, useEffect, useRef, useState } from "react";
interface RemotePullOpts {
- /**
- * Perform the pull without showing a global loading bar.
- *
- * Default: `false`.
- */
silent?: boolean;
}
@@ -72,13 +67,6 @@ export interface UploadProps {
type UploadType = "files" | "folders";
type WebUploadItemAndPath = [File, string];
-/**
- * Public album uploader.
- *
- * This is a trimmed copy of the photos app uploader that only keeps the web
- * flow needed by the public albums app: select or drop files/folders, ask for
- * the uploader's name, and upload into the current public collection.
- */
export const Upload: React.FC<UploadProps> = ({
publicAlbumsCredentials,
dragAndDropFiles,
@@ -124,10 +112,6 @@ export const Upload: React.FC<UploadProps> = ({
const selectedUploadType = useRef<UploadType | undefined>(undefined);
const currentUploadPromise = useRef<Promise<void> | undefined>(undefined);
- /**
- * `true` if we've activated one hidden input and are waiting for the
- * browser to hand the file selection back to us.
- */
const [isInputPending, setIsInputPending] = useState(false);
const [selectedInputFiles, setSelectedInputFiles] = useState<File[]>([]);
@@ -497,22 +481,6 @@ const Inputs: React.FC<InputsProps> = ({
</>
);
-/**
- * Return the relative path or name of a File object selected or
- * drag-and-dropped on the web.
- *
- * There are three cases here:
- *
- * 1. If the user selects individual file(s), then the returned File objects
- * will only have a `name`.
- *
- * 2. If the user selects directory(ies), then the returned File objects will
- * have a `webkitRelativePath`. For more details, see [Note:
- * webkitRelativePath]. In particular, these will POSIX separators.
- *
- * 3. If the user drags-and-drops, then react-dropzone internally converts
- * `webkitRelativePath` to `path`, but otherwise behaves the same as case 2.
- */
const pathLikeForWebFile = (file: File): string =>
firstNonEmpty([
"path" in file && typeof file.path == "string" ? file.path : undefined,
diff --git a/web/apps/albums/src/public-album/upload/components/UploaderNameInput.tsx b/web/apps/albums/src/public-album/upload/components/UploaderNameInput.tsx
index 78cf0a94e2..4f301a0e77 100644
--- a/web/apps/albums/src/public-album/upload/components/UploaderNameInput.tsx
+++ b/web/apps/albums/src/public-album/upload/components/UploaderNameInput.tsx
@@ -16,10 +16,6 @@ import { useFormik } from "formik";
import { t } from "i18next";
import React from "react";
-// =============================================================================
-// Sparkle Icons
-// =============================================================================
-
const SparkleTopRight: React.FC = () => (
<svg
width="14"
@@ -68,29 +64,12 @@ const SparkleBottomLeft: React.FC = () => (
</svg>
);
-// =============================================================================
-// Types
-// =============================================================================
-
type UploaderNameInputProps = ModalVisibilityProps & {
- /**
- * The existing uploader name to prefill.
- */
uploaderName: string;
- /**
- * Count of the number of files that the uploader is trying to upload.
- */
uploadFileCount: number;
- /**
- * Callback invoked when the user presses submit after entering a name.
- */
onSubmit: (name: string) => void | Promise<void>;
};
-/**
- * A dialog asking the uploader to a public album to provide their name so that
- * other folks can know who uploaded a given photo in the shared album.
- */
export const UploaderNameInput: React.FC<UploaderNameInputProps> = ({
open,
onClose,
@@ -139,12 +118,6 @@ export const UploaderNameInput: React.FC<UploaderNameInputProps> = ({
);
};
-/**
- * The form that obtains the textual input of the uploader name.
- *
- * It is kept as a separate component so that it gets recreated on prop changes
- * (e.g. uploaderName changes).
- */
export const UploaderNameInputForm: React.FC<
Omit<UploaderNameInputProps, "open">
> = ({ onClose, uploaderName, uploadFileCount, onSubmit }) => {
@@ -204,10 +177,6 @@ export const UploaderNameInputForm: React.FC<
);
};
-// =============================================================================
-// Styled Components
-// =============================================================================
-
const StyledDialog = styled(Dialog)(({ theme }) => ({
"& .MuiDialog-paper": {
width: 381,
diff --git a/web/apps/albums/src/public-album/upload/pipeline/export-dirs.ts b/web/apps/albums/src/public-album/upload/pipeline/export-dirs.ts
index d96b23ba28..352005049a 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/export-dirs.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/export-dirs.ts
@@ -1,5 +1 @@
-/**
- * Name of the directory in which we keep metadata sidecar files for exports and
- * uploads.
- */
export const exportMetadataDirectoryName = "metadata";
diff --git a/web/apps/albums/src/public-album/upload/pipeline/index.ts b/web/apps/albums/src/public-album/upload/pipeline/index.ts
index d267ce70e5..2fc795c016 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/index.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/index.ts
@@ -11,14 +11,8 @@ class UploadState {
const _state = new UploadState();
-/**
- * The public albums uploader only handles browser-provided Files.
- */
export type UploadItem = File;
-/**
- * Opaque folder-like context used when matching metadata JSON sidecars.
- */
export type UploadPathPrefix = string;
export const uploadPathPrefix = (pathOrName: string) => {
diff --git a/web/apps/albums/src/public-album/upload/pipeline/metadata-json.ts b/web/apps/albums/src/public-album/upload/pipeline/metadata-json.ts
index cee7318790..0b6b4d2c65 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/metadata-json.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/metadata-json.ts
@@ -1,5 +1,3 @@
-/** @file Dealing with the JSON metadata sidecar files */
-
import type {
UploadItem,
UploadPathPrefix,
@@ -8,18 +6,7 @@ import { nameAndExtension } from "ente-base/file-name";
import log from "ente-base/log";
import type { Location } from "ente-base/types";
-/**
- * The data we read from the JSON metadata sidecar files.
- *
- * The metadata JSON file format is similar to the JSON metadata sidecar format
- * produced by Google Takeout. This is so that the user can import their Google
- * Takeouts while preserving the metadata.
- *
- * During export the Ente app also writes out its own metadata in a similar and
- * compatible format so that the user can easily round trip (i.e. export their
- * data out of Ente, and import it back again). This also allows users to reuse
- * existing third party tools for working with the takeout format.
- */
+// Keep this compatible with both Takeout and Ente export sidecars.
export interface ParsedMetadataJSON {
creationTime?: number;
modificationTime?: number;
@@ -27,20 +14,6 @@ export interface ParsedMetadataJSON {
description?: string;
}
-/**
- * Derive a key for the given {@link jsonFileName} that should be used to index
- * into the {@link ParsedMetadataJSON} JSON map.
- *
- * @param pathPrefix The {@link UploadPathPrefix}, if available.
- *
- * @param collectionID The collection to which we're uploading.
- *
- * @param jsonFileName The file name for the JSON file.
- *
- * @returns A key suitable for indexing into the metadata JSON map.
- *
- * @see also {@link matchJSONMetadata}.
- */
export const metadataJSONMapKeyForJSON = (
pathPrefix: UploadPathPrefix | undefined,
collectionID: number,
@@ -58,51 +31,21 @@ const makeKey3 = (
fileName: string,
) => `${pathPrefix ?? ""}-${collectionID}-${fileName}`;
-/**
- * Return the matching entry, if any, from {@link parsedMetadataJSONMap} for the
- * {@link pathPrefix}, {@link collectionID} and {@link fileName} combination.
- *
- * This is the sibling of {@link metadataJSONMapKeyForJSON}, except for deriving
- * the filename key we might have to try a bunch of different variations, so
- * this does not return a single key but instead tries the combinations until it
- * finds an entry in the map, and returns the found entry instead of the key.
- *
- * In brief,
- *
- * - When inserting the metadata entry into {@link parsedMetadataJSONMap}, we
- * use {@link metadataJSONMapKeyForJSON}.
- *
- * - When reading back the metadata entry from {@link parsedMetadataJSONMap}, we
- * use {@link matchJSONMetadata}
- */
export const matchJSONMetadata = (
pathPrefix: UploadPathPrefix | undefined,
collectionID: number,
fileName: string,
parsedMetadataJSONMap: Map<string, ParsedMetadataJSON>,
) => {
- // Break the fileName down into its components.
let [name, extension] = nameAndExtension(fileName);
if (extension) {
extension = "." + extension;
}
- // Save the original name before any modifications for fallback lookups.
const originalName = name;
- // Trim off a suffix like "(1)" from the name, remembering what we trimmed
- // since we need to add it back later.
- //
- // It needs to be handled separately because of the clipping (see below).
- // The numbered suffix (if present) is not clipped. It is added at the end
- // of the clipped ".supplemental-metadata" portion, instead of after the
- // original filename.
- //
- // For example, "IMG_1234(1).jpg" would have a metadata filename of either
- // "IMG_1234.jpg(1).json" or "IMG_1234.jpg.supplemental-metadata(1).json".
- // And if the filename is too long, it gets turned into something like
- // "IMG_1234.jpg.suppl(1).json".
-
+ // Takeout moves "(n)" after the metadata suffix.
+ // It does not clip the numbered suffix.
let numberedSuffix = "";
const endsWithNumberedSuffixWithBrackets = /\(\d+\)$/.exec(name);
if (endsWithNumberedSuffixWithBrackets) {
@@ -110,30 +53,21 @@ export const matchJSONMetadata = (
numberedSuffix = endsWithNumberedSuffixWithBrackets[0];
}
- // Removes the "-edited" suffix, if present, so that the edited file can be
- // associated to the original file's metadataJSON file as edited files don't
- // have their own metadata files.
-
+ // Edited files share the original file's sidecar.
const editedFileSuffix = "-edited";
if (name.endsWith(editedFileSuffix)) {
name = name.slice(0, -1 * editedFileSuffix.length);
}
- // Convenience function to vary only the file name component when
- // constructing a key. Delegates to `makeKey3`.
const makeKey = (fn: string) => makeKey3(pathPrefix, collectionID, fn);
- // Derive a key from the collection name, file name and the suffix if any.
let baseFileName = `${name}${extension}`;
let key = makeKey(`${baseFileName}${numberedSuffix}`);
let takeoutMetadata = parsedMetadataJSONMap.get(key);
if (takeoutMetadata) return takeoutMetadata;
- // If the file name is greater than 46 characters, then Google Photos, with
- // its infinite storage, clips the file name. In such cases we need to use
- // the clipped file name to get the key.
-
+ // Takeout clips sidecar base names to 46 characters.
const maxGoogleFileNameLength = 46;
key = makeKey(
`${baseFileName.slice(0, maxGoogleFileNameLength)}${numberedSuffix}`,
@@ -142,20 +76,7 @@ export const matchJSONMetadata = (
takeoutMetadata = parsedMetadataJSONMap.get(key);
if (takeoutMetadata) return takeoutMetadata;
- // Newer Takeout exports are attaching a ".supplemental-metadata" suffix to
- // the file name of the metadataJSON file, you know, just to cause havoc,
- // and then clipping the file name if it's too long (ending up with
- // filenames "very_long_file_name.jpg.supple.json").
- //
- // Note that If the original filename is longer than 46 characters, then the
- // ".supplemental-metadata" suffix gets completely removed during the
- // clipping, along with a portion of the original filename (as before).
- //
- // For example, if the original filename is 45 characters long, then
- // everything except for the "." from ".supplemental-metadata" will get
- // clipped. So the metadata file ends up with a filename like
- // "filename_that_is_45_chars_long.jpg..json".
-
+ // Newer Takeout exports add this suffix before clipping.
const supplSuffix = ".supplemental-metadata";
baseFileName = `${name}${extension}${supplSuffix}`;
key = makeKey(
@@ -165,10 +86,7 @@ export const matchJSONMetadata = (
takeoutMetadata = parsedMetadataJSONMap.get(key);
if (takeoutMetadata) return takeoutMetadata;
- // Some Google Takeout exports keep the numbered suffix in its original
- // position instead of moving it to the end. For example, "skytree (2).jpg"
- // may have metadata in "skytree (2).jpg.supplemental-metadata.json" instead
- // of "skytree.jpg.supplemental-metadata(2).json". Try that pattern too.
+ // Some exports leave "(n)" in its original position.
if (numberedSuffix) {
const originalBaseFileName = `${originalName}${extension}${supplSuffix}`;
key = makeKey(originalBaseFileName.slice(0, maxGoogleFileNameLength));
@@ -178,9 +96,6 @@ export const matchJSONMetadata = (
return takeoutMetadata;
};
-/**
- * Try to parse the contents of a metadata JSON file from a Google Takeout.
- */
export const tryParseTakeoutMetadataJSON = async (
uploadItem: UploadItem,
): Promise<ParsedMetadataJSON | undefined> => {
@@ -197,17 +112,10 @@ const uploadItemText = async (uploadItem: UploadItem) =>
const parseMetadataJSONText = (text: string) => {
const metadataJSON_ = JSON.parse(text) as unknown;
- // Ignore non objects.
if (typeof metadataJSON_ != "object") return undefined;
- // Ignore null.
if (!metadataJSON_) return undefined;
- // Ignore arrays.
if (Array.isArray(metadataJSON_)) return undefined;
- // At this point, `metadataJSON_` is an `object`, but TypeScript won't let
- // me index it. The following is the simplest (but unsafe) way I could think
- // of for convincing TypeScript to allow me to index `metadataJSON` with
- // `string`s.
const metadataJSON = metadataJSON_ as Record<string, unknown>;
const parsedMetadataJSON: ParsedMetadataJSON = {};
@@ -231,15 +139,6 @@ const parseMetadataJSONText = (text: string) => {
return parsedMetadataJSON;
};
-/**
- * Parse a nullish epoch seconds timestamp string from a field in a Google
- * Takeout JSON, converting it into epoch microseconds if it is found.
- *
- * Note that the metadata provided by Google does not include the time zone
- * where the photo was taken, it only has an epoch seconds value. There is an
- * associated formatted date value (e.g. "17 Feb 2021, 03:22:16 UTC") but that
- * seems to be in UTC and doesn't have the time zone either.
- */
const parseGTTimestamp = (o: unknown): number | undefined => {
if (o && typeof o == "object" && "timestamp" in o) {
const ot = o.timestamp;
@@ -247,26 +146,17 @@ const parseGTTimestamp = (o: unknown): number | undefined => {
if (typeof ot == "string") {
timestamp = parseInt(ot, 10);
} else if (typeof ot == "number") {
- // Ente desktop 1.7.11 and earlier used to write out a number, which
- // is the correct datatype, but that makes it inconsistent with the
- // numbers-as-string that Google takeout writes.
- //
- // So now we write out strings, and read either.
+ // Older Ente exports used numbers; Takeout uses strings.
timestamp = Math.floor(ot);
}
if (timestamp && !Number.isNaN(timestamp)) {
+ // Takeout uses seconds; Ente uses microseconds.
return timestamp * 1e6;
}
}
return undefined;
};
-/**
- * Parse a (latitude, longitude) location pair field in a Google Takeout JSON.
- *
- * Apparently Google puts in (0, 0) to indicate missing data, so this function
- * only returns a parsed result if both components are present and non-zero.
- */
const parseGTLocation = (o: unknown): Location | undefined => {
if (
o &&
@@ -277,14 +167,11 @@ const parseGTLocation = (o: unknown): Location | undefined => {
typeof o.longitude == "number"
) {
const { latitude, longitude } = o;
+ // Takeout uses (0, 0) for missing locations.
if (latitude !== 0 || longitude !== 0) return { latitude, longitude };
}
return undefined;
};
-/**
- * Parse a string from a field in a Google Takeout JSON, treating empty strings
- * as undefined.
- */
const parseGTNonEmptyString = (o: unknown): string | undefined =>
o && typeof o == "string" ? o : undefined;
diff --git a/web/apps/albums/src/public-album/upload/pipeline/remote.ts b/web/apps/albums/src/public-album/upload/pipeline/remote.ts
index 486bb0b852..157c5c1b15 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/remote.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/remote.ts
@@ -11,28 +11,10 @@ import type { RemoteMagicMetadata } from "ente-media/magic-metadata";
import { nullToUndefined } from "ente-utils/transform";
import { z } from "zod";
-/**
- * A pre-signed URL alongwith the associated object key that is later used to
- * refer to file contents (the "object") that were uploaded to this URL.
- */
-const ObjectUploadURL = z.object({
- /**
- * The objectKey with which remote (both museum and the S3 bucket) will
- * refer to this object once it has been uploaded.
- */
- objectKey: z.string(),
- /**
- * A pre-signed URL that can be used to upload data to an S3-compatible
- * remote.
- */
- url: z.string(),
-});
+const ObjectUploadURL = z.object({ objectKey: z.string(), url: z.string() });
export type ObjectUploadURL = z.infer<typeof ObjectUploadURL>;
-/**
- * Fetch a pre-signed URL for uploading a public album file or thumbnail.
- */
export const fetchPublicAlbumsUploadURLWithMetadata = async (
{
contentLength,
@@ -56,9 +38,6 @@ export const fetchPublicAlbumsUploadURLWithMetadata = async (
return ObjectUploadURL.parse(await res.json());
};
-/**
- * Fetch multipart upload URLs for a large public album upload.
- */
export const fetchPublicAlbumsMultipartUploadURLsWithMetadata = async (
{
contentLength,
@@ -85,44 +64,14 @@ export const fetchPublicAlbumsMultipartUploadURLsWithMetadata = async (
return MultipartUploadURLs.parse(await res.json());
};
-/**
- * A list of URLs to use for multipart uploads.
- *
- * This is a list of pre-signed URLs (one for each part), a URL to indicate
- * completion, and an associated object key that is later used to refer to the
- * combined object from the parts there were uploaded to the part URLs.
- */
const MultipartUploadURLs = z.object({
- /**
- * The objectKey with which remote (museum and the S3 bucket) will refer to
- * this object once it has been uploaded.
- */
objectKey: z.string(),
- /**
- * A list of pre-signed URLs that can be used to upload the parts of the
- * entire file's data to an S3-compatible remote.
- */
partURLs: z.string().array(),
- /**
- * A pre-signed URL that can be used to finalize the multipart upload into a
- * single object on remote by providing the list of parts that were uploaded
- * (and their sequence) to the S3-compatible remote.
- */
completeURL: z.string(),
});
export type MultipartUploadURLs = z.infer<typeof MultipartUploadURLs>;
-/**
- * Upload a file using a pre-signed URL.
- *
- * @param fileUploadURL A pre-signed URL that can be used to upload data to the
- * remote S3-compatible storage.
- *
- * @param fileData The data to upload.
- *
- * @param retrier A function to wrap the request in retries if needed.
- */
interface PutFileOptions {
contentMd5?: string;
}
@@ -150,9 +99,6 @@ export const putFile = async (
}),
);
-/**
- * Variant of {@link putFile} that uses a CF worker.
- */
export const putFileViaWorker = async (
fileUploadURL: string,
fileData: Uint8Array<ArrayBuffer>,
@@ -173,24 +119,6 @@ export const putFileViaWorker = async (
}),
);
-/**
- * Upload a part of a multipart upload using a pre-signed URL.
- *
- * See: [Note: Multipart uploads].
- *
- * @param partUploadURL A pre-signed URL that can be used to upload data to the
- * remote S3-compatible storage.
- *
- * @param partData The part bytes to upload.
- *
- * @param retrier A function to wrap the request in retries if needed.
- *
- * @returns the value of the "ETag" header in the remote response, or
- * `undefined` if the ETag was not present in the response (this is not expected
- * from remote in case of a successful response, but it can happen in case the
- * user has some misconfigured browser extension which is blocking the ETag
- * header from being parsed).
- */
export const putFilePart = async (
partUploadURL: string,
partData: Uint8Array<ArrayBuffer>,
@@ -209,12 +137,10 @@ export const putFilePart = async (
body: partData,
}),
);
+ // Extensions or CORS can hide ETag after a successful upload.
return nullToUndefined(res.headers.get("etag"));
};
-/**
- * Variant of {@link putFilePart} that uses a CF worker.
- */
export const putFilePartViaWorker = async (
partUploadURL: string,
partData: Uint8Array<ArrayBuffer>,
@@ -238,84 +164,16 @@ export const putFilePartViaWorker = async (
return z.object({ etag: z.string() }).parse(await res.json()).etag;
};
-/**
- * Information about an individual part of a multipart upload that has been
- * uploaded to the remote (S3 or proxy).
- *
- * See: [Note: Multipart uploads].
- */
export interface MultipartCompletedPart {
- /**
- * The part number (1-indexed).
- *
- * The part number indicates the sequential ordering where this part belongs
- * in the overall file's data.
- */
+ // S3 part numbers start at 1.
partNumber: number;
- /**
- * The part "ETag".
- *
- * This is the Entity tag (retrieved as the "ETag" response header) returned
- * by remote when the part was uploaded.
- */
eTag: string;
}
-/**
- * Construct an XML string of the format expected as the request body for
- * {@link _completeMultipartUpload} or
- * {@link _completeMultipartUploadViaWorker}.
- *
- * @param parts Information about the parts that were uploaded.
- */
const createMultipartUploadRequestBody = (
parts: MultipartCompletedPart[],
): string => {
- // To avoid introducing a dependency on a XML library, we construct the
- // requisite XML by hand.
- //
- // Example:
- //
- // <CompleteMultipartUpload>
- // <Part>
- // <PartNumber>1</PartNumber>
- // <ETag>"1b3e6cdb1270c0b664076f109a7137c1"</ETag>
- // </Part>
- // <Part>
- // <PartNumber>2</PartNumber>
- // <ETag>"6049d6384a9e65694c833a3aca6584fd"</ETag>
- // </Part>
- // <Part>
- // <PartNumber>3</PartNumber>
- // <ETag>"331747eae8068f03b844e6f28cc0ed23"</ETag>
- // </Part>
- // </CompleteMultipartUpload>
- //
- //
- // Spec:
- // https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html
- //
- // <CompleteMultipartUpload>
- // <Part>
- // <PartNumber>integer</PartNumber>
- // <ETag>string</ETag>
- // </Part>
- // ...
- // </CompleteMultipartUpload>
- //
- // Note that in the example given on the spec page, the etag strings are quoted:
- //
- // <CompleteMultipartUpload>
- // <Part>
- // <PartNumber>1</PartNumber>
- // <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
- // </Part>
- // ...
- // </CompleteMultipartUpload>
- //
- // No extra quotes need to be added, the etag values we get from remote
- // already quoted, we just need to pass them verbatim.
-
+ // S3 returns quoted ETags; embed them verbatim.
const resultParts = parts.map(
(part) =>
`<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.eTag}</ETag></Part>`,
@@ -323,58 +181,6 @@ const createMultipartUploadRequestBody = (
return `<CompleteMultipartUpload>\n${resultParts.join("\n")}\n</CompleteMultipartUpload>`;
};
-/**
- * Complete a multipart upload by reporting information about all the uploaded
- * parts to the provided {@link completionURL}.
- *
- * @param completionURL A pre-signed URL to which the final status of the
- * uploaded parts should be reported to.
- *
- * @param completedParts Information about all the parts of the file that have
- * been uploaded. The part numbers must start at 1 and must be consecutive.
- *
- * @param retrier A function to wrap the request in retries if needed.
- *
- * [Note: Multipart uploads]
- *
- * Multipart uploads are a mechanism to upload large files onto an remote
- * storage bucket by breaking it into smaller chunks / "parts", uploading each
- * part separately, and then reporting the consolidated information of all the
- * uploaded parts to a URL that marks the upload as complete on remote.
- *
- * This allows greater resilience since uploads of individual parts can be
- * retried independently without failing the entire upload on transient network
- * issues. This also helps self hosters, since often cloud providers have limits
- * to the size of single requests that they'll allow through (e.g. the
- * Cloudflare free plan currently has a 100 MB request size limit).
- *
- * The flow is implemented in two ways:
- *
- * a. The normal way, where each requests is made to a remote S3 bucket directly
- * using the pre-signed URL.
- *
- * b. Using workers, where the requests are proxied via a worker near to the
- * user's network to speed the requests up.
- *
- * See [Note: Faster uploads via workers] for more details on the worker flow.
- *
- * In both cases, the overall flow is roughly like the following:
- *
- * 1. Obtain metadata-aware pre-signed URLs from the public album upload API.
- *
- * 2. Break the file to be uploaded into parts, and upload each part using a PUT
- * request to one of the pre-signed URLs we got in step 1. There are two
- * variants of this - one where we directly upload to the remote (S3)
- * ({@link putFilePart}), and one where we go via a worker
- * ({@link putFilePartViaWorker}).
- *
- * 3. Once all the parts have been uploaded, send a consolidated report of all
- * the uploaded parts (the step 2's) to remote via another pre-signed
- * "completion URL" that we also got in step 1. Like step 2, there are 2
- * variants of this - one where we directly tell the remote (S3)
- * ({@link completeMultipartUpload}), and one where we report via a worker
- * ({@link completeMultipartUploadViaWorker}).
- */
export const completeMultipartUpload = (
completionURL: string,
completedParts: MultipartCompletedPart[],
@@ -388,9 +194,6 @@ export const completeMultipartUpload = (
}),
);
-/**
- * Variant of {@link completeMultipartUpload} that uses a CF worker.
- */
export const completeMultipartUploadViaWorker = async (
completionURL: string,
completedParts: MultipartCompletedPart[],
@@ -418,60 +221,12 @@ export interface PostEnteFileRequest {
pubMagicMetadata?: RemoteMagicMetadata;
}
-/**
- * Attributes about an object uploaded to S3.
- *
- * This is similar to the {@link FileObjectAttributes} that we get back in the
- * {@link EnteFile} we get from remote, however it contains more fields.
- *
- * - When we're finalizing the upload of {@link EnteFile}, we have at our
- * disposal the {@link objectKey}, {@link decryptionHeader} and {@link size}
- * attributes that we need to set in the POST "/files" request.
- *
- * - Later when we get back the file from remote as an {@link EnteFile}, it will
- * only have the {@link decryptionHeader}. This is all we need for obtaining
- * the decrypted file: the contents of the file get fetched (on demand) using
- * a presigned URL, and the file's key is the decryption key, so armed with
- * this decryption header we are good to go.
- */
export interface UploadedFileObjectAttributes {
- /**
- * The "key" (unique ID) of the S3 object that was uploaded.
- *
- * This is not related to encryption, it is the "objectKey" that uniquely
- * identifies the S3 object that was uploaded. We get these as part of the
- * {@link ObjectUploadURL} we get from remote. We upload the contents of the
- * object (e.g. file, thumbnail) to the corresponding URL, and then report
- * back the "objectKey" in the upload finalization request.
- */
objectKey: string;
- /**
- * The decryption header that was used when encrypting the objects's
- * contents (with the file's key) before uploading them to S3 remote.
- *
- * The {@link decryptionHeader} is both required when finalizing the upload,
- * and is also returned as part of the {@link EnteFile} that clients get
- * back from remote since it is needed (along with the file's key) to
- * decrypt the object that the client would download from S3 remote.
- */
decryptionHeader: string;
- /**
- * The size of the uploaded object, in bytes.
- *
- * For both file and thumbnails, the client also sends the size of the
- * encrypted file (as per the client) while creating a new object on remote.
- * This allows the server to validate that the size of the objects is same
- * as what client is reporting.
- *
- * This should be present during upload, but is not returned back from
- * remote in the /diff response.
- */
size: number;
}
-/**
- * Create a new public album file on remote.
- */
export const postPublicAlbumsEnteFile = async (
postFileRequest: PostEnteFileRequest,
credentials: PublicAlbumsCredentials,
diff --git a/web/apps/albums/src/public-album/upload/pipeline/thumbnail.ts b/web/apps/albums/src/public-album/upload/pipeline/thumbnail.ts
index 20787300eb..1440cb6ed4 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/thumbnail.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/thumbnail.ts
@@ -6,43 +6,12 @@ import { heicToJPEG } from "ente-media/heic-convert";
import { scaledImageDimensions } from "ente-media/image";
import { withTimeout } from "ente-utils/promise";
-/** Maximum width or height of the generated thumbnail */
const maxThumbnailDimension = 720;
-/** Maximum size (in bytes) of the generated thumbnail */
-const maxThumbnailSize = 100 * 1024; // 100 KB
-
-/**
- * Timeout (ms) to wait before giving up on canvas thumbnail generation.
- *
- * [Note: Rendering arbitrary file types to the canvas needs a timeout]
- *
- * When generating thumbnails on the web, we use an HTML canvas. We take the
- * file's content, a blob, and load it on the canvas by creating an image URL
- * for this blob (using `createObjectURL`).
- *
- * In case when the browser knows how to render images of this type, this works
- * great. Later we can read off the thumbnail from the (resized) canvas.
- *
- * However, if this in not a file format that the browser can understand, then
- * this process just hangs. There isn't a trivial way of knowing beforehand
- * which browser will support which file type, so we need to add a timeout.
- */
+const maxThumbnailSize = 100 * 1024;
+
+// Unsupported image formats may never fire a load event.
const canvasThumbnailGenerationTimeout = 30 * 1000;
-/**
- * Generate a JPEG thumbnail for the given image or video blob.
- *
- * The thumbnail has a smaller file size so that is quick to load. But more
- * importantly, it uses a universal file format (JPEG in our case) so that the
- * thumbnail itself can be opened in all clients, even those like the web client
- * itself that might not yet have support for more exotic formats.
- *
- * @param blob The image or video blob whose thumbnail we want to generate.
- *
- * @param fileTypeInfo The type information for the file this blob came from.
- *
- * @return The JPEG data of the generated thumbnail.
- */
export const generateThumbnailWeb = async (
blob: Blob,
fileTypeInfo: FileTypeInfo,
@@ -170,10 +139,6 @@ export const generateVideoThumbnailUsingCanvas = async (blob: Blob) => {
return await compressedJPEGData(canvas);
};
-/**
- * A fallback, black, thumbnail for use in cases where thumbnail generation
- * fails.
- */
export const fallbackThumbnail = (): Uint8Array<ArrayBuffer> =>
Uint8Array.from(atob(blackThumbnailB64), (c) => c.charCodeAt(0));
diff --git a/web/apps/albums/src/public-album/upload/pipeline/upload-service.ts b/web/apps/albums/src/public-album/upload/pipeline/upload-service.ts
index f27d546957..478618f1ec 100644
--- a/web/apps/albums/src/public-album/upload/pipeline/upload-service.ts
+++ b/web/apps/albums/src/public-album/upload/pipeline/upload-service.ts
@@ -67,54 +67,16 @@ import { fallbackThumbnail, generateThumbnailWeb } from "./thumbnail";
const bitFlipErrorPrefix = "BitFlipDetected";
-/**
- * A readable stream for a file, and its associated size and last modified time.
- *
- * This is the in-memory representation of the {@link UploadItem} type that we
- * usually pass around. See: [Note: Reading a UploadItem]
- */
interface FileStream {
- /**
- * A stream of the file's contents
- *
- * This stream is guaranteed to emit data in
- * {@link streamEncryptionChunkSize} sized chunks (except the last chunk
- * which can be smaller since a file would rarely align exactly to a
- * {@link streamEncryptionChunkSize} multiple).
- *
- * Note: A stream can only be read once!
- */
stream: ReadableStream<Uint8Array>;
- /**
- * Number of chunks {@link stream} will emit, each
- * {@link streamEncryptionChunkSize} sized (except the last one).
- */
chunkCount: number;
- /**
- * The size in bytes of the underlying file.
- */
fileSize: number;
- /**
- * The modification time of the file, in epoch milliseconds.
- */
lastModifiedMs: number;
- /**
- * Set to the underlying {@link File} when we also have access to it.
- */
file?: File;
}
-/**
- * If the stream we have is more than 5 {@link streamEncryptionChunkSize}
- * chunks, then use multipart uploads for it, with each multipart-part
- * containing 5 chunks.
- *
- * {@link streamEncryptionChunkSize} is 4 MB, and the number of chunks in a
- * single upload part is 5, so each part is (up to) 20 MB.
- */
const multipartChunksPerPart = 5;
-/** Upload files to cloud storage */
class UploadService {
private publicAlbumsCredentials: PublicAlbumsCredentials | undefined;
@@ -186,69 +148,27 @@ class UploadService {
}
}
-/** The singleton instance of {@link UploadService}. */
const uploadService = new UploadService();
export default uploadService;
-/**
- * Return the file name for the given {@link uploadItem}.
- */
export const uploadItemFileName = (uploadItem: UploadItem) => uploadItem.name;
-/* -- Various intermediate types used during upload -- */
-
export type ExternalParsedMetadata = ParsedMetadata & {
creationTime?: number | undefined;
};
export interface UploadAsset {
- /**
- * `true` if this is a live photo.
- */
isLivePhoto?: boolean;
- /**
- * The two parts of the live photo being uploaded.
- *
- * Valid for live photos.
- */
livePhotoAssets?: LivePhotoAssets;
- /**
- * The item being uploaded.
- *
- * Valid for non-live photos.
- */
uploadItem?: UploadItem;
- /**
- * The path prefix of the uploadItem (if not a live photo), or of the image
- * component of the live photo (otherwise).
- *
- * The only expected scenario where this will not be present is when we're
- * uploading an edited file (edited in the in-app image editor).
- */
pathPrefix: UploadPathPrefix | undefined;
- /**
- * Metadata we know about a file externally. Valid for non-live photos.
- *
- * This is metadata that is not present within the file, but we have
- * available from external sources. There is also a parsed metadata we
- * obtain from JSON files. So together with the metadata present within the
- * file itself, there are three places where the file's initial metadata can
- * be filled in from.
- *
- * This will not be present for live photos.
- */
externalParsedMetadata?: ExternalParsedMetadata;
}
interface ThumbnailedFile {
fileStreamOrData: FileStream | Uint8Array<ArrayBuffer>;
- /** The JPEG data of the generated thumbnail */
thumbnail: Uint8Array<ArrayBuffer>;
- /**
- * `true` if this is a fallback (all black) thumbnail we're returning since
- * thumbnail generation failed for some reason.
- */
hasStaticThumbnail: boolean;
}
@@ -259,43 +179,19 @@ interface FileWithMetadata extends Omit<ThumbnailedFile, "hasStaticThumbnail"> {
}
interface EncryptedFileStream {
- /**
- * A stream of the file's encrypted contents
- *
- * This stream is guaranteed to emit data in
- * {@link streamEncryptionChunkSize} chunks (except the last chunk which can
- * be smaller since a file would rarely align exactly to a
- * {@link streamEncryptionChunkSize} multiple).
- */
stream: ReadableStream<Uint8Array<ArrayBuffer>>;
- /**
- * Number of chunks {@link stream} will emit, each
- * {@link streamEncryptionChunkSize} sized (except the last one).
- */
chunkCount: number;
}
interface EncryptedFilePieces {
- /**
- * The encrypted contents of the file (as bytes or a stream of bytes), and
- * the decryption header that was used during encryption (base64 string).
- */
file: {
encryptedData: Uint8Array<ArrayBuffer> | EncryptedFileStream;
decryptionHeader: string;
};
- /**
- * The encrypted contents of the file's thumbnail (as bytes), and the
- * decryption header that was used during encryption (base64 string).
- */
thumbnail: {
encryptedData: Uint8Array<ArrayBuffer>;
decryptionHeader: string;
};
- /**
- * The encrypted contents of the file's metadata (as a base64 string), and
- * the decryption header that was used during encryption (base64 string).
- */
metadata: { encryptedData: string; decryptionHeader: string };
pubMagicMetadata: RemoteMagicMetadata | undefined;
localID: number;
@@ -303,15 +199,13 @@ interface EncryptedFilePieces {
export interface PotentialLivePhotoAsset {
fileName: string;
- fileType: number /* FileType | -1 */;
+ // -1 means unknown.
+ fileType: number;
collectionID: number;
uploadItem: UploadItem;
pathPrefix: UploadPathPrefix | undefined;
}
-/**
- * Check if the two given assets should be clubbed together as a live photo.
- */
export const areLivePhotoAssets = async (
f: PotentialLivePhotoAsset,
g: PotentialLivePhotoAsset,
@@ -328,11 +222,7 @@ export const areLivePhotoAssets = async (
if (f.fileType == FileType.image && g.fileType == FileType.video) {
fPrunedName = removePotentialLivePhotoSuffix(
fName,
- // A Google Live Photo image file can have video extension appended
- // as suffix, so we pass that to removePotentialLivePhotoSuffix to
- // remove it.
- //
- // Example: IMG_20210630_0001.mp4.jpg (Google Live Photo image file)
+ // Google Live Photo images can be named like IMG_0001.mp4.jpg.
gExt ? `.${gExt}` : undefined,
);
gPrunedName = removePotentialLivePhotoSuffix(gName);
@@ -348,12 +238,8 @@ export const areLivePhotoAssets = async (
if (fPrunedName != gPrunedName) return false;
- // Also check that the size of an individual Live Photo asset is less than
- // an (arbitrary) limit. This should be true in practice as the videos for a
- // live photo are a few seconds long. Further on, the zipping library that
- // we use doesn't support stream as a input.
-
- const maxAssetSize = 20 * 1024 * 1024; /* 20MB */
+ // Live photos are read into memory before zipping.
+ const maxAssetSize = 20 * 1024 * 1024;
const fSize = uploadItemSize(f.uploadItem);
const gSize = uploadItemSize(g.uploadItem);
if (fSize > maxAssetSize || gSize > maxAssetSize) {
@@ -363,11 +249,7 @@ export const areLivePhotoAssets = async (
return false;
}
- // Finally, ensure that the creation times of the image and video are within
- // some epsilon of each other. This is to avoid clubbing together unrelated
- // items that coincidentally have the same name (this is not uncommon since,
- // e.g. many cameras use a deterministic numbering scheme).
-
+ // Camera filenames repeat, so matching names are not enough.
const fParsedMetadataJSON = matchJSONMetadata(
f.pathPrefix,
f.collectionID,
@@ -392,24 +274,14 @@ export const areLivePhotoAssets = async (
gParsedMetadataJSON,
);
- // The exact threshold to use is hard to decide. The times should be usually
- // exact to minute, but it is possible that one of the items is missing the
- // timezone while the other has it. Their dates (as shown by the app) would
- // both be correct, just the UTC epochs will vary.
- //
- // Using a threshold of 1 day makes the app more robust to such timezone
- // discrepancies while only marginally increasing the risk of false
- // positives. But this is a heuristic that might not always be correct.
- const thresholdSeconds = 24 * 60 * 60; /* 1 day */
+ // Allow one day because either asset may be missing timezone metadata.
+ const thresholdSeconds = 24 * 60 * 60;
const haveSameishDate =
fDate && gDate && Math.abs(fDate - gDate) / 1e6 < thresholdSeconds;
if (!haveSameishDate) {
- // Google does not include the metadata JSON for the video part of the
- // live photo in the Takeout, causing this date check to fail.
- //
- // So only incorporate this check if either neither file has a metadata
- // JSON, or both have it.
+ // Takeout omits some video sidecars.
+ // Enforce dates only when both assets have sidecars or neither does.
if (
(!fParsedMetadataJSON && !gParsedMetadataJSON) ||
(fParsedMetadataJSON && gParsedMetadataJSON)
@@ -418,17 +290,13 @@ export const areLivePhotoAssets = async (
}
}
- // All checks pass. Club these two as a live photo.
return true;
};
const removePotentialLivePhotoSuffix = (name: string, suffix?: string) => {
const suffix_3 = "_3";
- // The icloud-photos-downloader library appends _HVEC to the end of the
- // filename in case of live photos.
- //
- // https://github.com/icloud-photos-downloader/icloud_photos_downloader
+ // icloud-photos-downloader appends "_HVEC" to Live Photo names.
const suffix_hvec = "_HVEC";
let foundSuffix: string | undefined;
@@ -448,33 +316,15 @@ const removePotentialLivePhotoSuffix = (name: string, suffix?: string) => {
return foundSuffix ? name.slice(0, foundSuffix.length * -1) : name;
};
-/**
- * Return the size of the given {@link uploadItem}.
- */
const uploadItemSize = (uploadItem: UploadItem): number => {
return uploadItem.size;
};
-/**
- * Return the creation date for the given {@link uploadItem}.
- *
- * [Note: Duplicate retrieval of creation date for live photo clubbing]
- *
- * This function duplicates some logic of {@link extractImageOrVideoMetadata}.
- * This duplication, while not good, is currently unavoidable with the way the
- * code is structured since the live photo clubbing happens at an earlier time
- * in the pipeline when we don't have the Exif data, but the Exif data is needed
- * to determine the file's creation time (to ensure that we only club photos and
- * videos with close by creation times, instead of just relying on file names).
- *
- * Note that unlike {@link extractImageOrVideoMetadata}, we don't try to
- * fallback to the file's modification time. This is because for the purpose of
- * live photo clubbing, we wish to use the creation date only in cases where we
- * have it.
- */
+// Live-photo matching happens before full metadata extraction.
+// Do not fall back to modification time here.
const uploadItemCreationDate = async (
uploadItem: UploadItem,
- fileType: number /* FileType */,
+ fileType: number,
parsedMetadataJSON: ParsedMetadataJSON | undefined,
) => {
if (parsedMetadataJSON?.creationTime)
@@ -494,133 +344,28 @@ const uploadItemCreationDate = async (
return parsedMetadata?.creationDate?.timestamp;
};
-/**
- * The message of the {@link Error} that is thrown when the user cancels an
- * upload.
- *
- * As a convenience, the {@link isUploadCancelledError} matcher can be used to
- * match such errors.
- *
- * [Note: Upload cancellation]
- *
- * 1. User cancels the upload by pressing the cancel button on the upload
- * progress indicator in the UI.
- *
- * 2. This sets the {@link shouldUploadBeCancelled} flag on
- * {@link UploadManager}.
- *
- * 3. Periodically the code that is performing the upload calls the
- * {@link abortIfCancelled} flag. This function is a no-op normally, but if
- * the {@link shouldUploadBeCancelled} is set then it throws an {@link Error}
- * with the message set to {@link uploadCancelledErrorMessage}.
- *
- * 4. The intermediate per-file try catch handlers do not intercept this error,
- * and it bubbles all the way to the top of the call stack, ending the upload.
- */
export const uploadCancelledErrorMessage = "Upload cancelled";
-/**
- * A convenience function to check if the provided value is an {@link Error}
- * with message {@link uploadCancelledErrorMessage}.
- */
export const isUploadCancelledError = (e: unknown) =>
e instanceof Error && e.message == uploadCancelledErrorMessage;
-/**
- * The message of the {@link Error} that is thrown when the upload fails because
- * the user's current session has expired (e.g. maybe they logged this client
- * out from another session), and that they need to login again.
- */
export const sessionExpiredErrorMessage = "Session expired";
-/**
- * The message of the {@link Error} that is thrown when the upload fails because
- * the user's subscription has expired.
- */
export const subscriptionExpiredErrorMessage = "Subscription expired";
-/**
- * The message of the {@link Error} that is thrown when the upload fails because
- * the user's storage space has been exhausted.
- */
export const storageLimitExceededErrorMessage = "Storage limit exceeded";
-/**
- * The message of the {@link Error} that is thrown when the PUT request for the
- * upload of a part of file (as part of an overall multipart upload) fails
- * because the response did not have the etag error.
- *
- * This usually happens because some browser extension is blocking access to the
- * ETag header (even when it is present in the remote S3 response). In self
- * hosted scenarios, this can also happen if the remote S3 bucket does not have
- * the appropriate CORS rules to allow access to the etag header.
- */
const eTagMissingErrorMessage = "ETag header not present in response";
-/**
- * The message of the {@link Error} that is thrown when the size of the file
- * being uploaded exceeds the maximum allowed file size.
- *
- * The client already checks for the size of the file being uploaded, and aborts
- * the request if the client side limit is exceeded. An error with this message
- * is thrown if we remote side validation fails.
- *
- * The UI outcome is the same in both cases.
- */
const fileTooLargeErrorMessage = "File too large";
-/**
- * Some state and callbacks used during upload that are not tied to a specific
- * file being uploaded.
- */
interface UploadContext {
- /**
- * If `true`, then the upload does not go via the worker.
- *
- * See {@link shouldDisableCFUploadProxy} for more details.
- */
isCFUploadProxyDisabled: boolean;
- /**
- * If present, then the upload is happening in the context of the public
- * albums app and these are the credentials that should be used for
- * performing API requests (instead of trying to obtain and use the
- * credentials for the logged in user, as happens when we're running in the
- * context of the photos app).
- */
publicAlbumsCredentials: PublicAlbumsCredentials | undefined;
- /**
- * A function that the upload sequence should use to periodically check in
- * and see if the upload has been cancelled by the user.
- *
- * If the upload has been cancelled, it will throw an exception with the
- * message set to {@link uploadCancelledErrorMessage}.
- *
- * See: [Note: Upload cancellation]
- */
abortIfCancelled: () => void;
- /**
- * A function that gets called update the progress shown in the UI for a
- * particular file as the parts of that file get uploaded.
- *
- * @param {fileLocalID} The local ID of the file whose progress we want to
- * update.
- *
- * @param {percentage} The upload completion percentage, as a value between
- * 0 and 100 (inclusive).
- */
updateUploadProgress: (fileLocalID: number, percentage: number) => void;
}
-/**
- * Upload the given {@link UploadableUploadItem}
- *
- * This is lower layer implementation of the upload. It is invoked by
- * {@link UploadManager} after it has assembled all the relevant bits we need to
- * go forth and upload.
- *
- * @param uploadContext Some general state and callbacks for the entire set of
- * files being uploaded.
- */
export const upload = async (
{ collection, localID, fileName, ...uploadAsset }: UploadableUploadItem,
uploaderName: string | undefined,
@@ -633,22 +378,6 @@ export const upload = async (
log.info(`Upload ${fileName} | start`);
try {
- /*
- * We read the file four times:
- * 1. To determine its MIME type (only needs first few KBs).
- * 2. To extract its metadata.
- * 3. To calculate its hash.
- * 4. To encrypt it.
- *
- * When we already have a File object the multiple reads are fine.
- *
- * There might be room to optimize further by using
- * `ReadableStream.tee` to perform these steps simultaneously.
- * However, that'll require restructuring the code so that these steps
- * run in a parallel manner (tee will not work for strictly sequential
- * reads of large streams).
- */
-
let assetDetails: ReadAssetDetailsResult;
try {
@@ -665,7 +394,7 @@ export const upload = async (
if (fileSize === 0) return { type: "zeroSize" };
- const maxFileSize = 10 * 1024 * 1024 * 1024; /* 10 GB */
+ const maxFileSize = 10 * 1024 * 1024 * 1024;
if (fileSize >= maxFileSize) return { type: "tooLarge" };
abortIfCancelled();
@@ -689,8 +418,6 @@ export const upload = async (
const matchInSameCollection = matches.find(
(f) => f.collectionID == collection.id,
);
- // The public albums uploader only writes into the current public
- // collection, and its dedup state is scoped to that collection.
return {
type: "alreadyUploaded",
file: matchInSameCollection ?? anyMatch,
@@ -752,19 +479,16 @@ export const upload = async (
};
} catch (e) {
if (isUploadCancelledError(e)) {
- /* stop the upload */
throw e;
}
log.error(`Upload failed for ${fileName}`, e);
switch (e instanceof Error && e.message) {
- /* stop the upload */
case sessionExpiredErrorMessage:
case subscriptionExpiredErrorMessage:
case storageLimitExceededErrorMessage:
throw e;
- /* file specific */
case eTagMissingErrorMessage:
return { type: "blocked" };
case fileTooLargeErrorMessage:
@@ -775,11 +499,6 @@ export const upload = async (
}
};
-/**
- * Convert specific HTTP errors during an API call to remote endpoints for
- * fetching new upload URLs into error with known messages (if applicable).
- *
- */
const translateURLFetchErrorIfNeeded = (e: unknown) => {
if (e instanceof HTTPError) {
switch (e.res.status) {
@@ -794,14 +513,6 @@ const translateURLFetchErrorIfNeeded = (e: unknown) => {
return e;
};
-/**
- * Read the given file into an in-memory representation.
- *
- * [Note: Reading a UploadItem]
- *
- * The public albums uploader only deals with browser-provided
- * [File](https://developer.mozilla.org/en-US/docs/Web/API/File) objects.
- */
const readUploadItem = (uploadItem: UploadItem): FileStream => {
const file = uploadItem;
const underlyingStream = file.stream();
@@ -811,9 +522,8 @@ const readUploadItem = (uploadItem: UploadItem): FileStream => {
const N = streamEncryptionChunkSize;
const chunkCount = Math.ceil(fileSize / streamEncryptionChunkSize);
- // Pipe the underlying stream through a transformer that emits
- // streamEncryptionChunkSize-ed chunks (except the last one, which can be
- // smaller).
+ // Encryption requires fixed-size chunks.
+ // Only the final chunk may be smaller.
let pending: Uint8Array | undefined;
const transformer = new TransformStream<Uint8Array, Uint8Array>({
transform(
@@ -851,10 +561,6 @@ interface ReadAssetDetailsResult {
lastModifiedMs: number;
}
-/**
- * Read the associated file(s) to determine the type, size and last modified
- * time of the given {@link asset}.
- */
const readAssetDetails = async ({
isLivePhoto,
livePhotoAssets,
@@ -873,8 +579,7 @@ const readLivePhotoDetails = async ({ image, video }: LivePhotoAssets) => {
return {
fileTypeInfo: {
fileType: FileType.livePhoto,
- // Use the extension of the image component as the extension of the
- // live photo.
+ // A live photo uses its image extension.
extension: img.fileTypeInfo.extension,
},
fileSize: img.fileSize + vid.fileSize,
@@ -882,15 +587,6 @@ const readLivePhotoDetails = async ({ image, video }: LivePhotoAssets) => {
};
};
-/**
- * Read the beginning of the given file to determine its MIME type. From that,
- * construct and return a {@link FileTypeInfo}.
- *
- * While we're at it, also return the size of the file, and its last modified
- * time (expressed as epoch milliseconds).
- *
- * @param uploadItem See: [Note: Reading a UploadItem]
- */
const readImageOrVideoDetails = async (uploadItem: UploadItem) => {
const { stream, fileSize, lastModifiedMs } = readUploadItem(uploadItem);
@@ -905,14 +601,6 @@ const readImageOrVideoDetails = async (uploadItem: UploadItem) => {
return { fileTypeInfo, fileSize, lastModifiedMs };
};
-/**
- * Read the entirety of a readable stream.
- *
- * It is not recommended to use this for large (say, multi-hundred MB) files. It
- * is provided as a syntactic shortcut for cases where we already know that the
- * size of the stream will be reasonable enough to be read in its entirety
- * without us running out of memory.
- */
const readEntireStream = async (
stream: ReadableStream,
): Promise<Uint8Array<ArrayBuffer>> =>
@@ -923,10 +611,6 @@ interface ExtractAssetMetadataResult {
publicMagicMetadata: FilePublicMagicMetadataData;
}
-/**
- * Compute the hash, extract Exif or other metadata, and merge in data from the
- * {@link parsedMetadataJSONMap} for the assets. Return the resultant metadatum.
- */
const extractAssetMetadata = async (
{
isLivePhoto,
@@ -1022,18 +706,12 @@ const extractImageOrVideoMetadata = async (
);
}
- // The `UploadAsset` itself might have metadata associated with a-priori, if
- // so, merge the data we read from the file's contents into it.
if (externalParsedMetadata) {
parsedMetadata = { ...externalParsedMetadata, ...parsedMetadata };
}
const hash = await computeHash(uploadItem, worker);
- // Some of this logic is duplicated in `uploadItemCreationDate`.
- //
- // See: [Note: Duplicate retrieval of creation date for live photo clubbing]
-
const parsedMetadataJSON = matchJSONMetadata(
pathPrefix,
collectionID,
@@ -1061,21 +739,13 @@ const extractImageOrVideoMetadata = async (
tryParseEpochMicrosecondsFromFileName(fileName) ?? modificationTime;
}
- // Video duration
let duration: number | undefined;
if (fileType == FileType.video) {
duration = await tryDetermineVideoDuration(uploadItem);
}
- // To avoid introducing malformed data into the metadata fields (which the
- // other clients might not expect and handle), we have extra "ensure" checks
- // here that act as a safety valve if somehow the TypeScript type is lying.
- //
- // There is no deterministic sample we found that necessitated adding these
- // extra checks, but we did get one user with a list in the width field of
- // the metadata (it should've been an integer). The most probable theory is
- // that somehow it made its way in through malformed Exif.
-
+ // Malformed Exif has put arrays in numeric fields.
+ // Keep these runtime checks even though TypeScript considers them redundant.
const metadata: FileMetadata = {
fileType,
title: fileName,
@@ -1152,19 +822,6 @@ const tryDetermineVideoDuration = async (uploadItem: UploadItem) => {
}
};
-/**
- * Compute the hash of an item we're attempting to upload.
- *
- * The hash is retained in the file metadata, and is also used to detect
- * duplicates during upload.
- *
- * This process can take a noticable amount of time. As an extreme case, for a
- * 10 GB upload item, this can take a 2-3 minutes.
- *
- * @param uploadItem The {@link UploadItem} we're attempting to upload.
- *
- * @param worker A {@link CryptoWorker} to use for computing the hash.
- */
const computeHash = async (uploadItem: UploadItem, worker: CryptoWorker) => {
const { stream, chunkCount } = readUploadItem(uploadItem);
const hashState = await worker.chunkHashInit();
@@ -1181,23 +838,13 @@ const computeHash = async (uploadItem: UploadItem, worker: CryptoWorker) => {
return await worker.chunkHashFinal(hashState);
};
-/**
- * Return true if the given file is the same as provided metadata.
- *
- * Note that the metadata includes the hash of the file's contents (when
- * available), so this also in effect compares the contents of the files, not
- * just the "meta" information about them.
- */
const areFilesSame = (fFile: EnteFile, gm: FileMetadata) => {
const fm = fFile.metadata;
- // File name is different.
if (fileFileName(fFile) != gm.title) return false;
- // File type is different.
if (fm.fileType != gm.fileType) return false;
- // Name and type is same, compare hash.
const fh = metadataHash(fm);
const gh = metadataHash(gm);
return fh && gh && fh == gh;
@@ -1223,20 +870,11 @@ const readLivePhoto = async (
hasStaticThumbnail,
} = await augmentWithThumbnail(
livePhotoAssets.image,
- // For live photos, the extension field in the file type info is the
- // extension of the image component of the live photo.
{ fileType: FileType.image, extension: fileTypeInfo.extension },
readUploadItem(livePhotoAssets.image),
);
const videoFileStreamOrData = readUploadItem(livePhotoAssets.video);
- // The JS zip library that encodeLivePhoto uses does not support
- // ReadableStreams, so pass the file (blob) if we have one, otherwise read
- // the entire stream into memory and pass the resultant data.
- //
- // This is a reasonable behaviour since the videos corresponding to live
- // photos are only a couple of seconds long (we've already done a pre-flight
- // check during areLivePhotoAssets to ensure their size is small).
const fileOrData = async (sd: FileStream | Uint8Array<ArrayBuffer>) => {
const fos = async ({ file, stream }: FileStream) =>
file ? file : await readEntireStream(stream);
@@ -1263,18 +901,6 @@ const readImageOrVideo = async (
return augmentWithThumbnail(uploadItem, fileTypeInfo, fileStream);
};
-/**
- * Augment the given {@link dataOrStream} with thumbnail information.
- *
- * This is a companion method for {@link readUploadItem}, and can be used to
- * convert the result of {@link readUploadItem} into an {@link ThumbnailedFile}.
- *
- * @param uploadItem The {@link UploadItem} where the given {@link fileStream}
- * came from.
- *
- * Note: The `fileStream` in the returned {@link ThumbnailedFile} may be
- * different from the one passed to the function.
- */
const augmentWithThumbnail = async (
uploadItem: UploadItem,
fileTypeInfo: FileTypeInfo,
@@ -1410,10 +1036,6 @@ const encryptFileStream = async (
async pull(controller) {
const { value, done } = await fileStreamReader.read();
if (done) {
- // TransformStream in readUploadItem guarantees that we'll get
- // encryption sized `chunkCount` chunks. Below we close the
- // controller on the last chunk. So we shouldn't be getting a
- // `done` here.
controller.close();
throw new Error("Unexpected stream state");
}
@@ -1487,12 +1109,7 @@ const uploadToBucket = async (
const requestRetrier = createAbortableRetryEnsuringHTTPOk(abortIfCancelled);
- // The bulk of the network time during upload is taken in uploading the
- // actual encrypted objects to remote S3, but after that there is another
- // API request we need to make to "finalize" the file (on museum). This
- // should be quick usually, but it's a different network route altogether
- // and we can't know for sure how long it'll take. So keep aside a small
- // approximate percentage for this last step.
+ // Leave room for the final API request.
const maxPercent = Math.floor(95 + 5 * Math.random());
let fileObjectKey: string;
@@ -1503,8 +1120,6 @@ const uploadToBucket = async (
!(encryptedData instanceof Uint8Array) &&
encryptedData.chunkCount >= multipartChunksPerPart
) {
- // We have a stream, and it is more than multipartChunksPerPart
- // chunks long, so use a multipart upload to upload it.
({ objectKey: fileObjectKey, fileSize } =
await uploadStreamUsingMultipart(
localID,
@@ -1586,22 +1201,6 @@ const uploadToBucket = async (
};
};
-/**
- * A factory method that returns a function which will act like variant of
- * {@link retryEnsuringHTTPOk} and also understands the cancellation mechanism
- * used by the upload subsystem.
- *
- * @param abortIfCancelled A function that aborts the operation by throwing a
- * error with the message set to {@link uploadCancelledErrorMessage} if the user
- * has cancelled the upload.
- *
- * @return A function of type {@link HTTPRequestRetrier} that can be used to
- * retry requests. This function will retry requests (obtained afresh each time
- * by calling the provided {@link request} function) in the same manner as
- * {@link retryEnsuringHTTPOk}. Additionally, it will call
- * {@link abortIfCancelled} before each attempt, and also bypass the retries
- * when the abort happens on such cancellations.
- */
const createAbortableRetryEnsuringHTTPOk =
(abortIfCancelled: () => void): HTTPRequestRetrier =>
(request, opts) =>
@@ -1633,8 +1232,7 @@ const uploadStreamUsingMultipart = async (
const { stream } = dataStream;
const streamReader = stream.getReader();
- // Public album uploads always request metadata-aware multipart URLs, so we
- // first materialize each part to compute its checksum.
+ // The API needs every part checksum before it returns upload URLs.
const parts: Uint8Array<ArrayBuffer>[] = [];
const partMd5s: string[] = [];
let fileSize = 0;
@@ -1713,11 +1311,6 @@ const uploadStreamUsingMultipart = async (
return { objectKey: multipartUploadURLs.objectKey, fileSize };
};
-/**
- * Construct byte arrays, up to 20 MB each, containing the contents of (up to)
- * the next 5 {@link streamEncryptionChunkSize} chunks read from the given
- * {@link streamReader}.
- */
const nextMultipartUploadPart = async (
streamReader: ReadableStreamDefaultReader<Uint8Array>,
) => {
@@ -1730,9 +1323,6 @@ const nextMultipartUploadPart = async (
return mergeUint8Arrays(chunks);
};
-/**
- * Finalize an upload by creating an {@link EnteFile} on remote.
- */
const createRemoteFile = async (
newFileRequest: PostEnteFileRequest,
uploadContext: UploadContext,
diff --git a/web/apps/albums/src/public-album/upload/services/upload-manager.ts b/web/apps/albums/src/public-album/upload/services/upload-manager.ts
index 540c50c78e..feaa6e0572 100644
--- a/web/apps/albums/src/public-album/upload/services/upload-manager.ts
+++ b/web/apps/albums/src/public-album/upload/services/upload-manager.ts
@@ -37,7 +37,6 @@ import { wait } from "ente-utils/promise";
export type FileID = number;
export type PercentageUploaded = number;
-/* localID => fileName */
export type UploadFileNames = Map<FileID, string>;
export interface UploadCounter {
@@ -50,10 +49,6 @@ export interface InProgressUpload {
progress: PercentageUploaded;
}
-/**
- * A variant of {@link UploadResult}'s {@link type} values used when segregating
- * finished uploads in the UI.
- */
export type FinishedUploadType = UploadResult["type"];
export type InProgressUploads = Map<FileID, PercentageUploaded>;
@@ -76,9 +71,9 @@ export interface ProgressUpdater {
setHasLivePhotos: React.Dispatch<React.SetStateAction<boolean>>;
}
-/** The number of uploads to process in parallel. */
const maxConcurrentUploads = 4;
+// A retried live photo has livePhotoAssets instead of uploadItem.
export type UploadItemWithCollection = UploadAsset & {
localID: number;
collectionID: number;
@@ -89,12 +84,10 @@ class UIService {
// @ts-ignore
private progressUpdater: ProgressUpdater;
- // UPLOAD LEVEL STATES
private uploadPhase: UploadPhase = "preparing";
private filenames = new Map<number, string>();
private hasLivePhoto = false;
- // STAGE LEVEL STATES
private perFileProgress = 0;
private filesUploadedCount = 0;
private totalFilesCount = 0;
@@ -188,7 +181,6 @@ class UIService {
// eslint-disable-next-line @typescript-eslint/no-unused-vars
for (const [_, progress] of this.inProgressUploads) {
- // filter negative indicator values during percentComplete calculation
if (progress < 0) {
continue;
}
@@ -202,13 +194,6 @@ class UIService {
setFinishedUploads(groupByResult(this.finishedUploads));
}
- /**
- * Update the upload progress shown in the UI to {@link percentage} for the
- * file with the given {@link fileLocalID}.
- *
- * @param percentage The upload completion percentage. It should be a value
- * between 0 and 100 (inclusive).
- */
updateUploadProgress(fileLocalID: number, percentage: number) {
this.inProgressUploads.set(fileLocalID, Math.round(percentage));
this.updateProgressBarUI();
@@ -244,11 +229,6 @@ class UploadManager {
private uploadInProgress = false;
private publicAlbumsCredentials: PublicAlbumsCredentials | undefined;
private uploaderName: string | undefined;
- /**
- * When `true`, then the next call to {@link abortIfCancelled} will throw.
- *
- * See: [Note: Upload cancellation].
- */
private shouldUploadBeCancelled = false;
private uiService = new UIService();
@@ -282,25 +262,6 @@ class UploadManager {
this.uiService.setUploadPhase("preparing");
}
- /**
- * Upload files
- *
- * This method waits for all the files to get uploaded (successfully or
- * unsuccessfully) before returning.
- *
- * It is an error to call this method when there is already an in-progress
- * upload.
- *
- * @param itemsWithCollection The items to upload, each paired with the id
- * of the collection that they should be uploaded into.
- *
- * @param collections The collections to which the files are being uploaded.
- *
- * These are not all the user's collections - these are just the collections
- * mentioned by one or more {@link itemsWithCollection}.
- *
- * @returns `true` if at least one file was processed
- */
public async uploadItems(
itemsWithCollection: UploadItemWithCollection[],
collections: Collection[],
@@ -338,8 +299,6 @@ class UploadManager {
this.abortIfCancelled();
- // Live photos might've been clustered together, reset the list
- // of files to reflect that.
this.uiService.setFiles(clusteredMediaItems);
this.uiService.setHasLivePhoto(
@@ -477,7 +436,6 @@ class UploadManager {
switch (uploadResult.type) {
case "failed":
case "blocked":
- // Retriable error.
this.failedItems.push(uploadableItem);
break;
@@ -496,10 +454,6 @@ class UploadManager {
this.shouldUploadBeCancelled = true;
}
- /**
- * Return the list of failed items from the last upload, along with other
- * state needed to attempt to reupload them.
- */
public failedItemState() {
return {
items: [...this.failedItems],
@@ -517,55 +471,16 @@ class UploadManager {
this.onUploadFile!(file);
}
- /**
- * `true` if an upload is currently in-progress.
- */
public isUploadInProgress = () => {
return this.uploadInProgress;
};
}
-/**
- * Singleton instance of {@link UploadManager}.
- */
export const uploadManager = new UploadManager();
-/**
- * The data operated on by the intermediate stages of the upload.
- *
- * [Note: Intermediate file types during upload]
- *
- * As files progress through stages, they get more and more bits tacked on to
- * them. These types document the journey.
- *
- * - The input is {@link UploadItemWithCollection}. This can either be a new
- * {@link UploadItemWithCollection}, in which case it'll only have a
- * {@link localID}, {@link collectionID} and a {@link uploadItem}. Or it could
- * be a retry, in which case it'll not have a {@link uploadItem} but instead
- * will have data from a previous stage (concretely, it'll just be a
- * relabelled {@link ClusteredUploadItem}), like a snake eating its tail.
- *
- * - Immediately we convert it to {@link UploadItemWithCollectionIDAndName}.
- * This is to mostly systematize what we have, and also attach a
- * {@link fileName}.
- *
- * - These then get converted to "assets", whereby both parts of a live photo
- * are combined. This is a {@link ClusteredUploadItem}.
- *
- * - On to the {@link ClusteredUploadItem} we attach the corresponding
- * {@link collection}, giving us {@link UploadableUploadItem}. This is what
- * gets queued and then passed to the {@link upload}.
- */
type UploadItemWithCollectionIDAndName = UploadAsset & {
- /** A unique ID for the duration of the upload */
localID: number;
- /** The ID of the collection to which this file should be uploaded. */
collectionID: number;
- /**
- * The name of the file.
- *
- * In case of live photos, this'll be the name of the image part.
- */
fileName: string;
};
@@ -602,10 +517,6 @@ const splitMetadataAndMediaItems = (
],
);
-/**
- * Go through the given files, combining any sibling image + video assets into a
- * single live photo when appropriate.
- */
const clusterLivePhotos = async (
_items: UploadItemWithCollectionIDAndName[],
parsedMetadataJSONMap: Map<string, ParsedMetadataJSON>,
@@ -652,8 +563,6 @@ const clusterLivePhotos = async (
});
index += 2;
} else {
- // They may already be a live photo (we might be retrying a
- // previously failed upload).
result.push({ ...fa, isLivePhoto: fa.isLivePhoto ?? false });
index += 1;
}
diff --git a/web/packages/base/i18n.ts b/web/packages/base/i18n.ts
index 150fce4797..7c8ad7cb23 100644
--- a/web/packages/base/i18n.ts
+++ b/web/packages/base/i18n.ts
@@ -6,159 +6,71 @@ import i18n from "i18next";
import resourcesToBackend from "i18next-resources-to-backend";
import { initReactI18next } from "react-i18next";
-/**
- * List of all {@link SupportedLocale}s.
- *
- * Locales are combinations of a language code, and an optional region code.
- *
- * For example, "en", "en-US", "en-IN" (Indian English), "pt" (Portuguese),
- * "pt-BR" (Brazilian Portuguese).
- *
- * In our Crowdin Project, we have work-in-progress translations into more
- * languages than this. When a translation reaches a high enough coverage, say
- * 90%, then we manually add it to this list of supported languages.
- */
+// Enable locales only after their Crowdin translations reach roughly 90%.
export const supportedLocales = [
- "en-US" /* English */,
- "fr-FR" /* French */,
- "de-DE" /* German */,
- "ca-ES" /* Catalan */,
- "zh-CN" /* Simplified Chinese */,
- "zh-TW" /* Traditional Chinese */,
- "nl-NL" /* Dutch */,
- "es-ES" /* Spanish */,
- "pt-PT" /* Portuguese */,
- "pt-BR" /* Portuguese, Brazilian */,
- "ru-RU" /* Russian */,
- "pl-PL" /* Polish */,
- "it-IT" /* Italian */,
- "lt-LT" /* Lithuanian */,
- "uk-UA" /* Ukrainian */,
- "ur-IN" /* Urdu, India */,
- "vi-VN" /* Vietnamese */,
- "ja-JP" /* Japanese */,
- "ar-SA" /* Arabic */,
- "tr-TR" /* Turkish */,
- "cs-CZ" /* Czech */,
- "el-GR" /* Greek */,
+ "en-US",
+ "fr-FR",
+ "de-DE",
+ "ca-ES",
+ "zh-CN",
+ "zh-TW",
+ "nl-NL",
+ "es-ES",
+ "pt-PT",
+ "pt-BR",
+ "ru-RU",
+ "pl-PL",
+ "it-IT",
+ "lt-LT",
+ "uk-UA",
+ "ur-IN",
+ "vi-VN",
+ "ja-JP",
+ "ar-SA",
+ "tr-TR",
+ "cs-CZ",
+ "el-GR",
] as const;
-/** The type of {@link supportedLocales}. */
export type SupportedLocale = (typeof supportedLocales)[number];
const defaultLocale: SupportedLocale = "en-US";
-/**
- * Load translations and add custom formatters.
- *
- * Localization and related concerns (aka "internationalization", or "i18n") for
- * our apps is handled by i18n framework.
- *
- * In addition to the base i18next package, we use two of its plugins:
- *
- * - i18next-http-backend, for loading the JSON files containing the translations
- * at runtime, and
- *
- * - react-i18next, which adds React specific APIs
- *
- * This function also adds our custom formatters. They can be used within the
- * translated strings by using `{{val, formatterName}}`. For more details, see
- * https://www.i18next.com/translation-function/formatting.
- *
- * Our custom formatters:
- *
- * - "date": Formats an epoch microsecond value into a string containing the
- * year, month and day of the the date. For example, under "en-US" it'll
- * produce a string like "July 19, 2024".
- */
export const setupI18n = async () => {
const localeString = localStorage.getItem("locale") ?? undefined;
const locale = closestSupportedLocale(localeString);
- // https://www.i18next.com/overview/api
await i18n
- // i18next-resources-to-backend: Use webpack to bundle translation, but
- // still fetch them lazily using a dynamic import.
- //
- // The benefit of this is that, unlike the http backend that uses files
- // from the public folder, these JSON files are content hash named and
- // eminently cacheable.
- //
- // https://github.com/i18next/i18next-resources-to-backend
.use(
resourcesToBackend(
(language: string, namespace: string) =>
import(`./locales/${language}/${namespace}.json`),
),
)
- // react-i18next: React support
- // Pass the i18n instance to react-i18next.
.use(initReactI18next)
- // Initialize i18next
- // Option docs: https://www.i18next.com/overview/configuration-options
.init({
debug: isDevBuild,
- // i18next calls it language, but it really is the locale
lng: locale,
- // Tell i18next about the locales we support
supportedLngs: supportedLocales,
- // Ask it to fetch only exact matches
- //
- // By default, if the lng was set to, say, en-GB, i18n would make
- // network requests for ["en-GB", "en", "dev"] (where dev is the
- // default fallback). By setting `load` to "currentOnly", we ask
- // i18next to only try and fetch "en-GB" (i.e. the exact match).
load: "currentOnly",
- // Disallow empty strings as valid translations.
- //
- // This way, empty strings will fallback to `fallbackLng`
returnEmptyString: false,
- // The language to use if translation for a particular key in the
- // current `lng` is not available.
fallbackLng: defaultLocale,
interpolation: {
- escapeValue: false, // not needed for react as it escapes by default
+ escapeValue: false, // React escapes interpolated values.
},
react: {
useSuspense: false,
- // Allow the following tags (without any attributes) to be used
- // in translations. Such keys can then be rendered using the
- // Trans component, but without otherwise needing any other
- // input from our side.
- //
- // https://react.i18next.com/latest/trans-component
transKeepBasicHtmlNodesFor: ["br", "p", "strong", "code"],
},
});
- // To use this in a translation, interpolate as `{{val, date}}`.
i18n.services.formatter?.addCached("date", (locale) => {
- // The "long" dateStyle:
- //
- // - Includes: year (y), long-month (MMMM), day (d)
- // - English pattern examples: MMMM d, y ("September 14, 1999")
- //
const formatter = Intl.DateTimeFormat(locale, { dateStyle: "long" });
- // Value is an epoch microsecond so that we can directly pass the
- // timestamps we get from our API responses. The formatter expects
- // milliseconds, so divide by 1000.
- //
- // See [Note: Remote timestamps are epoch microseconds].
+ // API timestamps are microseconds; DateTimeFormat expects milliseconds.
return (val) => formatter.format(val / 1000);
});
};
-/**
- * Return the closest / best matching {@link SupportedLocale}.
- *
- * It takes as input a {@link savedLocaleString}, which denotes the user's
- * explicitly chosen preference (which we then persist in local storage).
- * Subsequently, we use this to (usually literally) return the supported locale
- * that it represents.
- *
- * If {@link savedLocaleString} is `undefined`, it tries to deduce the closest
- * {@link SupportedLocale} that matches the browser's locale.
- */
const closestSupportedLocale = (
savedLocaleString?: string,
): SupportedLocale => {
@@ -166,10 +78,8 @@ const closestSupportedLocale = (
if (ss && includes(supportedLocales, ss)) return ss;
for (const ls of getUserLocales()) {
- // Exact match
if (ls && includes(supportedLocales, ls)) return ls;
- // Language match
if (ls.startsWith("en")) {
return "en-US";
} else if (ls.startsWith("fr")) {
@@ -192,8 +102,6 @@ const closestSupportedLocale = (
} else if (ls.startsWith("es")) {
return "es-ES";
} else if (ls.startsWith("pt-BR")) {
- // We'll never get here (it'd already be an exact match), just kept
- // to keep this list consistent.
return "pt-BR";
} else if (ls.startsWith("pt")) {
return "pt-PT";
@@ -224,23 +132,14 @@ const closestSupportedLocale = (
}
}
- // Fallback
return defaultLocale;
};
-/**
- * Return the locale that is currently being used to show the app's UI.
- *
- * Note that this may be different from the user's locale. For example, the
- * browser might be set to en-GB, but since we don't support that specific
- * variant of English, this value will be (say) en-US.
- */
export const getLocaleInUse = (): SupportedLocale => {
const locale = i18n.resolvedLanguage;
if (locale && includes(supportedLocales, locale)) {
return locale;
} else {
- // This shouldn't have happened. Log an error to attract attention.
log.error(
`Expected the i18next locale to be one of the supported values, but instead found ${locale}`,
);
@@ -248,12 +147,6 @@ export const getLocaleInUse = (): SupportedLocale => {
}
};
-/**
- * Set the locale that should be used to show the app's UI.
- *
- * This updates both the i18next state, and also the corresponding user
- * preference that is stored in local storage.
- */
export const setLocaleInUse = async (locale: SupportedLocale) => {
localStorage.setItem("locale", locale);
return i18n.changeLanguage(locale);
@@ -261,75 +154,23 @@ export const setLocaleInUse = async (locale: SupportedLocale) => {
let _numberFormat: Intl.NumberFormat | undefined;
-/**
- * Lazily created, cached, instance of NumberFormat used by
- * {@link formattedNumber}.
- *
- * See: [Note: Changing locale causes a full reload].
- */
const numberFormat = () =>
(_numberFormat ??= new Intl.NumberFormat(i18n.language));
-/**
- * Return the given {@link value} formatted for the current language and locale.
- *
- * In most cases, when a number needs to be displayed, it can be formatted as
- * part of the surrounding string using the {{count, number}} interpolation.
- * However, in some rare cases, we need to format a standalone number. For such
- * scenarios, this function can be used.
- */
export const formattedNumber = (value: number) => numberFormat().format(value);
let _listJoinFormat: Intl.ListFormat | undefined;
-/**
- * Lazily created, cached, instance of NumberFormat used by
- * {@link formattedListJoin}.
- *
- * See: [Note: Changing locale causes a full reload].
- */
const listJoinFormat = () =>
(_listJoinFormat ??= new Intl.ListFormat(i18n.language, {
style: "narrow",
}));
-/**
- * Return the given {@link items} joined together into a single string using an
- * locale specific "comma like" separator.
- *
- * Usually this will just use a comma (plus space) as the list item separator,
- * but depending on the locale it might use a different separator too.
- *
- * e.g. ["Foo", "Bar"] becomes "Foo, Bar" in "en-US" and "Foo、Bar" in "zh".
- */
export const formattedListJoin = (value: string[]) =>
listJoinFormat().format(value);
-/**
- * A no-op marker for strings that, for various reasons, pending addition to the
- * translation dataset.
- *
- * This function does nothing, it just returns back the passed it string
- * verbatim. It is only kept as a way for us to keep track of strings which
- * we've not yet added to the list of strings that should be translated (e.g.
- * perhaps we're awaiting feedback on the copy).
- *
- * It is the sibling of the {@link t} function provided by i18next.
- *
- * See also: {@link ut}.
- */
+// Marks user-visible text pending translation.
export const pt = (s: string) => s;
-/**
- * A no-op marker for strings that, for various reasons, are not translated.
- *
- * This function does nothing, it just returns back the passed it string
- * verbatim. It is only kept as a way for us to keep track of strings that are
- * not translated (and for some reason, are currently not meant to be), but
- * still are user visible.
- *
- * It is the sibling of the {@link t} function provided by i18next.
- *
- * See also: {@link pt}.
- */
+// Marks intentionally untranslated text.
export const ut = (s: string) => s;