Skip to content

armgit / ente

Public Imported from GitHub
0

💚 End-to-end encrypted cloud for everything.

Prune comments from web subsystems

Manav Rathi71dd64e80b99
diff --git a/web/apps/photos/src/components/Collections/CollectionMapDialog.tsx b/web/apps/photos/src/components/Collections/CollectionMapDialog.tsx
index d3b0782d6a..e2b57364d7 100644
--- a/web/apps/photos/src/components/Collections/CollectionMapDialog.tsx
+++ b/web/apps/photos/src/components/Collections/CollectionMapDialog.tsx
@@ -78,12 +78,6 @@ interface CollectionMapDialogProps
onRemotePull?: (opts?: RemotePullOpts) => Promise<void>;
}
-// Describes all map-related state used in the dialog:
-// - mapCenter: current map center, typically derived from the latest file with location
-// - mapIndex/mapPoints/latestFileId: spatial index and its source points, plus the newest file id
-// - filesByID/thumbByFileID: cached file metadata and lazily-fetched thumbnails
-// - isLoading/error: loading/error flags for map data fetches
-
interface MapDataState {
mapCenter: [number, number] | null;
mapIndex: MapIndex | null;
@@ -95,36 +89,18 @@ interface MapDataState {
error: string | null;
}
-/**
- * When files are being opened from the the Sidebar, there is ablity to add them as favoriate,
- * archive them or unarchieve them and this interface is for facilitating that. Where the favoruteFileIds
- * hols the existing favorites, pending holds the ones which are in progress for respective ones
- */
-
interface FavoritesState {
favoriteFileIDs: Set<number>;
pendingFavoriteUpdates: Set<number>;
pendingVisibilityUpdates: Set<number>;
}
-/**
- * Extension of MapDataState that adds mutation functions for map data management.
- * - removeFiles: Removes files from the map index when deleted from FileListWithViewer
- * - updateFileVisibility: Updates file visibility state and removes hidden files from the map
- * - queueThumbnailFetch: Batches and fetches thumbnails on demand for visible files
- */
-
interface MapDataResult extends MapDataState {
removeFiles: (fileIDs: number[]) => void;
updateFileVisibility: (file: EnteFile, visibility: ItemVisibility) => void;
queueThumbnailFetch: (fileIDs: number[]) => void;
}
-/**
- * Dynamically loaded map components to avoid SSR issues with Leaflet. Normal imports actually caused
- * the app to break in some instances, thus dynamically loading them instead.
- * Loaded lazily in useMapComponents() hook when the dialog opens to ensure window exists.
- */
interface MapComponents {
MapContainer: typeof import("react-leaflet").MapContainer;
TileLayer: typeof import("react-leaflet").TileLayer;
@@ -132,15 +108,6 @@ interface MapComponents {
useMap: typeof import("react-leaflet").useMap;
}
-/**
- * Represents a geotagged photo point stored in the map spatial index.
- * Each point corresponds to a photo with location metadata.
- * - fileId: Unique identifier for the photo file
- * - lat: Latitude coordinate of the photo location
- * - lng: Longitude coordinate of the photo location
- * - timestamp: Millisecond sort key in the local photo timeline.
- */
-
interface MapIndexPoint {
fileId: number;
lat: number;
@@ -157,51 +124,22 @@ interface MapPhotoPoint {
fileId: number;
}
-/**
- * Along with the GeoTagged photos we are also storing a metadata, which changes
- * only when there is change in the stored values, to prevent this from updating
- * each time when there is change. Currently fileCount and updationTime are the
- * two metrics kept to analyse this change.
- */
-
-/**
- * The small payload we attach to a point: fileId points to the photo, and
- * timestamp keeps enough local-photo timeline context for sorting or choosing
- * the freshest item in a cluster.
- */
interface MapPointProperties {
fileId: number;
timestamp: number;
}
-/**
- * A GeoJSON feature for a single photo point. GeoJSON is the small, common shape most map
- * libraries expect for geographic data, so we stick with it even when we only need a
- * couple of fields. type stays "Feature" because that is the GeoJSON spec's envelope for
- * real-world points; it does not change our logic, but it keeps the data recognizable to
- * tooling like Supercluster. properties carry the fileId and timestamp (and keep cluster
- * as false), and geometry stores the point in [lng, lat] order for map libs.
- */
interface MapPointFeature {
type: "Feature";
properties: MapPointProperties & { cluster?: false };
geometry: { type: "Point"; coordinates: [number, number] };
}
-/**
- * Summary info for a cluster: latestTimestamp and latestFileId keep track of the freshest
- * photo inside the cluster so we can choose a representative cover.
- */
interface MapClusterProperties {
latestTimestamp: number;
latestFileId: number;
}
-/**
- * A GeoJSON feature that represents a cluster instead of a single point. properties mark
- * it as a cluster, carry cluster_id for expansion, point_count for the raw size, and
- * point_count_abbreviated for a compact label, while geometry still gives the centroid.
- */
interface MapClusterFeature {
type: "Feature";
properties: MapClusterProperties & {
@@ -213,16 +151,8 @@ interface MapClusterFeature {
geometry: { type: "Point"; coordinates: [number, number] };
}
-/**
- * Convenience union so callers can handle clusters and single points together.
- */
type MapFeature = MapClusterFeature | MapPointFeature;
-/**
- * The small contract we rely on from Supercluster: load ingests points, getClusters
- * returns mixed clusters/points for bounds and zoom, getLeaves expands a cluster into
- * its points, and getClusterExpansionZoom tells us how far to zoom to break it apart.
- */
interface MapIndex {
load(points: MapPointFeature[]): MapIndex;
getClusters(
@@ -237,11 +167,6 @@ interface MapIndex {
getClusterExpansionZoom(clusterId: number): number;
}
-/**
- * Tuning knobs for building the index: radius controls cluster size in pixels, maxZoom
- * caps clustering depth, map shapes point data into the cluster properties we track,
- * and reduce merges those properties as clusters grow.
- */
interface MapClusterOptions {
radius?: number;
maxZoom?: number;
@@ -254,27 +179,18 @@ interface MapClusterOptions {
type SuperclusterConstructor = new (options?: MapClusterOptions) => MapIndex;
-//OpenStreetMap only supports clustering till this zoom level and this tell the supercluster what the max limit is for the zoom.
const MAX_MAP_ZOOM = 19;
const DEFAULT_MAP_ZOOM = 10;
-//Instead of loading just the tiles which are in view, we're actually loading the 15% of the surrounding zone as well for smoother experience.
-//Leaflet LatLngBounds.pad expects a ratio (0.15 = 15%).
const PREFETCH_BOUNDS_PADDING = 0.15;
-//This count controls how many thumbnails are fetched in each batch when loading images for the markers
const THUMBNAIL_BATCH_SIZE = 40;
-/**
- * This is the first hook which is being loaded when the CollectionMapDialog is mounted
- * Dynamically loads map-related React components (Leaflet) to avoid SSR issues
- * Responsibility: Lazy load map dependencies only when needed (window must exist)
- */
function useMapComponents() {
const [mapComponents, setMapComponents] = useState<MapComponents | null>(
null,
);
useEffect(() => {
- // Only load on client-side where window exists, and updates the state with the components.
+ // Static react-leaflet imports break SSR.
if (typeof window === "undefined") return;
void import("react-leaflet")
@@ -294,10 +210,6 @@ function useMapComponents() {
return mapComponents;
}
-/**
- * Retrieves the current authenticated user data and throws error if the user is not loggedIn.
- * Responsibility: Provide user context for favorite/visibility operations
- */
function useCurrentUser() {
return useMemo(() => {
try {
@@ -327,35 +239,10 @@ interface DeriveLocationAwareMapFilesParams {
const emptyFileIDs = new Set<number>();
-/**
- *
- * @param collectionSummaryType
- * @returns Checks if the current active collection is All or userFavorites
- * if so then we return true.
- *
- * This function is relevant because in All and Favorites album we have to handle
- * the shared favorite files seperately.
- */
const shouldUseLocationAwareMapRepresentatives = (
collectionSummaryType: CollectionSummary["type"],
) => collectionSummaryType == "all" || collectionSummaryType == "userFavorites";
-/**
- *
- * @param file The file for which we are checking whether the file
- * can be used as a MapEquivalent.
- *
- * @param hiddenFileIDs The list of files which are hidden by the user
- * @param archivedFileIDs The list of files which are archieved by the user
- * @param tempDeletedFileIDs The list of files which are just deleted.
- * @param tempHiddenFileIDs The list of the files which are just hidden.
- *
- * the tempDeletedFileIDs and the tempHiddenFileIDs hold the IDs of the files
- * on which the action was just performed, and the remotePull hasn't happened yet
- * so without these variables, a just-hidden/deleted file might still show up
- * as an MapEquivalent file.
- * @returns
- */
const canUseFileAsMapEquivalent = (
file: EnteFile,
hiddenFileIDs: Set<number>,
@@ -363,13 +250,12 @@ const canUseFileAsMapEquivalent = (
tempDeletedFileIDs: Set<number>,
tempHiddenFileIDs: Set<number>,
) => {
- // If the file is hidden, deleted or archieved then returning false.
+ // A mutation can be remote before the next pull updates collectionFiles.
if (tempDeletedFileIDs.has(file.id)) return false;
if (hiddenFileIDs.has(file.id)) return false;
if (tempHiddenFileIDs.has(file.id)) return false;
if (archivedFileIDs.has(file.id)) return false;
- // Confirming that the file's visiblity is set to visible/undefined.
const visibility = file.magicMetadata?.data.visibility;
return visibility === undefined || visibility === ItemVisibility.visible;
};
@@ -395,10 +281,6 @@ const deriveLocationAwareMapFiles = ({
tempDeletedFileIDs,
tempHiddenFileIDs,
}: DeriveLocationAwareMapFilesParams) => {
- // If there is no loggedIn user or if the album is not
- // All or Favorites then returning the files which we got
- // from the gallery itself without any additional
- // shared-favorite swapping or handling.
if (
!currentUserID ||
!shouldUseLocationAwareMapRepresentatives(collectionSummaryType)
@@ -408,8 +290,6 @@ const deriveLocationAwareMapFiles = ({
const filesByHashAndType = new Map<string, EnteFile[]>();
for (const file of collectionFiles) {
- // If a file doesn't statisfy the requirements of showing
- // up as a MapEquivalent then skipping it.
if (
!canUseFileAsMapEquivalent(
file,
@@ -422,12 +302,10 @@ const deriveLocationAwareMapFiles = ({
continue;
}
- // If the file can be shown in the map getting the FileHashAndTypeKey
const key = favoriteFileHashAndTypeKey(file);
if (!key) continue;
- // Grouping the same files using their FileHashAndTypeKey as the key.
const matchingFiles = filesByHashAndType.get(key);
if (matchingFiles) {
matchingFiles.push(file);
@@ -439,20 +317,15 @@ const deriveLocationAwareMapFiles = ({
const mapFiles: EnteFile[] = [];
const mapFileIDs = new Set<number>();
- // Looping through the files which we got passed down from the gallery.
for (const file of files) {
const key = favoriteFileHashAndTypeKey(file);
const equivalentFiles = key ? filesByHashAndType.get(key) : undefined;
- // if there is no equivalentFiles it means that the file has only one copy
- // which is the original copy so keep it that.
if (!equivalentFiles) {
addUniqueMapFile(mapFiles, mapFileIDs, file);
continue;
}
- // If we are in the All view, we check if any of the equivalentFiles
- // are favorited, if not then we pass the original file to the addUniqueMapFile
if (
collectionSummaryType == "all" &&
!equivalentFiles.some((equivalentFile) =>
@@ -463,10 +336,6 @@ const deriveLocationAwareMapFiles = ({
continue;
}
- // If we get here, the file has equivalentFiles and atleast one
- // of them is favorited. So we split the equivalent files according
- // to their ownership.
-
const ownedFiles = equivalentFiles.filter(
(equivalentFile) => equivalentFile.ownerID == currentUserID,
);
@@ -474,10 +343,6 @@ const deriveLocationAwareMapFiles = ({
(equivalentFile) => equivalentFile.ownerID != currentUserID,
);
- /**
- * If there is not both an owned and shared side, it keeps the original file.
- * The special logic only matters when the same underlying media exists as both an owned copy and a shared copy.
- */
if (!ownedFiles.length || !sharedFiles.length) {
addUniqueMapFile(mapFiles, mapFileIDs, file);
continue;
@@ -487,7 +352,6 @@ const deriveLocationAwareMapFiles = ({
const sharedFilesWithLocation = sharedFiles.filter(fileLocation);
if (ownedFilesWithLocation.length && sharedFilesWithLocation.length) {
- // both owned and shared have location: add shared-with-location, then owned-with-location
for (const sharedFile of sharedFilesWithLocation) {
addUniqueMapFile(mapFiles, mapFileIDs, sharedFile);
}
@@ -495,17 +359,14 @@ const deriveLocationAwareMapFiles = ({
addUniqueMapFile(mapFiles, mapFileIDs, ownedFile);
}
} else if (sharedFilesWithLocation.length) {
- // only shared has location: add shared-with-location
for (const sharedFile of sharedFilesWithLocation) {
addUniqueMapFile(mapFiles, mapFileIDs, sharedFile);
}
} else if (ownedFilesWithLocation.length) {
- // only owned has location: add owned-with-location
for (const ownedFile of ownedFilesWithLocation) {
addUniqueMapFile(mapFiles, mapFileIDs, ownedFile);
}
} else {
- // neither has location: keep the original file
addUniqueMapFile(mapFiles, mapFileIDs, file);
}
}
@@ -541,25 +402,11 @@ const deriveFavoriteFileIDs = (
return favoriteFileIDs;
};
-/**
- *
- * @param files
- * @returns points, latestFileId
- *
- * This function create the inital mapIndexPoint any collection.
- * It's later this points
- * that is being given to the supercluster for the mapping and indexing.
- *
- * This function loops over the entire files which is suspect is not EFFICENT
- * but currently it loads about 1,00,000 images seamlessly which is far better
- * than the earlier implementation we had.
- */
const buildMapIndexPoints = async (files: EnteFile[]) => {
const points: MapIndexPoint[] = [];
let latestTimestamp = -1;
let latestFileId: number | undefined;
- //looping over each file to extract their time and location to create the point
for (let index = 0; index < files.length; index += 1) {
const file = files[index];
if (!file) continue;
@@ -579,11 +426,7 @@ const buildMapIndexPoints = async (files: EnteFile[]) => {
latestFileId = file.id;
}
- /**
- * This pauses the event loop briefly, so the main thead is not blocked if there are mutliple so many files.
- * This doesn't change the complexisty of this loop, just keep the thread responsive for UI updates, input and rendering.
- */
-
+ // Keep 100k-file collections responsive.
if (index > 0 && index % 5000 === 0) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
@@ -592,24 +435,7 @@ const buildMapIndexPoints = async (files: EnteFile[]) => {
return { points, latestFileId };
};
-/**
- *
- * @param points
- * @returns a SuperCluster Spatial Index, using which we can retrive (1)the clusters/points for a particular bbox + zoom level
- * (2) all leaves under a cluster. (3) the maximum zoom for a particular cluster
- *
- * This function converts every MapIndexPoint to a GeoJSON Feature(required for rendering
- * using supercluster)[type MapPointFeature]. NOTE this index is not persisted.
- */
const buildClusterIndex = (points: MapIndexPoint[]): MapIndex => {
- /**
- * - For every point we load, Supercluster calls map(props) once to decide what
- * cluster metadata that point contributes.
- *
- * - When multiple points are to begrouped into a cluster, Supercluster repeatedly calls
- * reduce(accumulated, props) to merge those per‑point metadata objects into a single cluster summary.
- */
-
const options: MapClusterOptions = {
radius: 80,
maxZoom: MAX_MAP_ZOOM,
@@ -628,7 +454,6 @@ const buildClusterIndex = (points: MapIndexPoint[]): MapIndex => {
const SuperclusterCtor = Supercluster as unknown as SuperclusterConstructor;
const index = new SuperclusterCtor(options);
- // converting MapIndexPoint -> MapPointFeature
const features: MapPointFeature[] = points.map((point) => ({
type: "Feature" as const,
properties: { fileId: point.fileId, timestamp: point.timestamp },
@@ -638,7 +463,6 @@ const buildClusterIndex = (points: MapIndexPoint[]): MapIndex => {
},
}));
- //builds the spaital cluster hierachy across various zoom level
index.load(features);
return index;
};
@@ -654,15 +478,6 @@ const getPointByFileId = (
return points.find((point) => point.fileId === fileId);
};
-/**
- *
- * @param points
- * @returns MapIndexPoint
- *
- * Though we are computing the latestFile while loadMapData(), sometimes
- * if this latestFile is deleted or archieved by the user then we need
- * to compute a new latestFile, this is the purpose this fn serves.
- */
const getLatestPointByTimestamp = (
points: MapIndexPoint[],
): MapIndexPoint | undefined => {
@@ -678,10 +493,6 @@ const getLatestPointByTimestamp = (
const getLatestFileIdFromPoints = (points: MapIndexPoint[]) =>
getLatestPointByTimestamp(points)?.fileId;
-/**
- * Loads and manages map data including index, files, and thumbnails.
- * Responsibility: Fetch collection files, build/persist spatial index, prefetch thumbnails on demand.
- */
const emptyMapDataState = (): MapDataState => ({
mapCenter: null,
mapIndex: null,
@@ -701,30 +512,21 @@ function useMapData(
): MapDataResult {
const [state, setState] = useState<MapDataState>(emptyMapDataState);
- //Ref mirroring the filesByID(state) to prevent the stale closure issue with the queueThumbnailFetch useCallback fn().
const filesByIDRef = useRef<Map<number, EnteFile>>(new Map());
- //Ref mirroring the thumbByFileID state to prevent the same issue as above
const thumbsByFileIDRef = useRef<Map<number, string>>(new Map());
- //A work queue with the list of fileIDs waiting to have their thumbs fetched.
const pendingThumbsRef = useRef<Set<number>>(new Set());
const isThumbnailWorkerRunningRef = useRef(false);
- // Track which collection we've loaded to avoid unnecessary reloads
- // Include fileCount to detect when collection content changes
const loadedCollectionRef = useRef<{
summaryId: number;
fileCount: number;
updationTime: number | null;
files: EnteFile[];
} | null>(null);
- // Survives dialog close (unlike loadedCollectionRef, which is cleared on
- // close) so we can tell a same-collection background reload apart from a
- // switch to a different collection.
const lastLoadedSummaryIdRef = useRef<number | undefined>(undefined);
- // Invalidates in-flight loads when a newer load starts or the dialog closes.
+ // Closing or a newer load invalidates in-flight work.
const loadGenerationRef = useRef(0);
- //Syncing the refs with the state for the stale closure prevention.
useEffect(() => {
filesByIDRef.current = state.filesByID;
}, [state.filesByID]);
@@ -740,13 +542,6 @@ function useMapData(
const existingThumbs = thumbsByFileIDRef.current;
const filesByID = filesByIDRef.current;
- /**
- * Loops through the fileIds for which thumbnails are to fetched,
- * and if thumbs are already generated or that fileId doesn't exist
- * then skipping it.
- *
- * Otherwise adding it to the ref for the fetching process
- */
for (const fileId of fileIDs) {
if (existingThumbs.has(fileId)) continue;
if (!filesByID.has(fileId)) continue;
@@ -758,11 +553,6 @@ function useMapData(
void (async () => {
while (pendingThumbsRef.current.size > 0) {
- /**
- * Since we're fetching in a batched manner, slicing the THUMBNAIL_BATCH_SIZE for fetching and
- * removing these from the pending list.
- */
-
const batchIds = Array.from(pendingThumbsRef.current).slice(
0,
THUMBNAIL_BATCH_SIZE,
@@ -785,9 +575,6 @@ function useMapData(
}),
);
- /**
- * Updating the existing state with the newly fetched thumbnails.
- */
setState((prev) => {
const updatedThumbMap = new Map(prev.thumbByFileID);
entries.forEach(([fileId, thumbnailUrl]) => {
@@ -800,7 +587,6 @@ function useMapData(
: prev;
});
- //To yield control between batches os the UI stays responsive
await new Promise((resolve) => setTimeout(resolve, 0));
}
@@ -808,7 +594,6 @@ function useMapData(
})();
}, []);
- // Clear loaded ref when dialog closes so we reload fresh data next time.
useEffect(() => {
if (!open) {
loadedCollectionRef.current = null;
@@ -821,16 +606,12 @@ function useMapData(
useEffect(() => {
if (!open) return;
- // Skip reload if we already have data for this collection with same file count
const currentSummaryId = collectionSummary.id;
const currentFileCount = collectionSummary.fileCount;
const currentUpdationTime = collectionSummary.updationTime ?? null;
const loaded = loadedCollectionRef.current;
- // The files array identity changes on every remote pull (e.g. the
- // desktop app pulls on each window focus), so compare stable file
- // revisions to avoid tearing down the map for a no-op reload while
- // still detecting metadata changes such as edited locations.
+ // Pulls replace the array, so compare revisions to catch real edits only.
const sameFiles =
loaded?.files === files ||
(!!loaded &&
@@ -844,7 +625,6 @@ function useMapData(
);
}));
- //preventing reloading of the data if it's already loaded.
if (
loaded?.summaryId === currentSummaryId &&
loaded.fileCount === currentFileCount &&
@@ -856,12 +636,8 @@ function useMapData(
const loadMapData = async () => {
const generation = ++loadGenerationRef.current;
- //In this ref we are actually setting a new Set() so clearing that before any compute happens.
pendingThumbsRef.current.clear();
- // When switching to a different collection, blank the previous
- // collection's map data so it doesn't flash while the new one
- // loads; for a same-collection reload, keep it mounted behind the
- // background refresh.
+ // Clear stale maps on a switch; keep background reloads mounted.
const isNewCollection =
lastLoadedSummaryIdRef.current !== currentSummaryId;
setState((prev) =>
@@ -873,18 +649,15 @@ function useMapData(
try {
const uniqueFiles = uniqueFilesByID(files);
- //Creating a id <- file mapping to drive renders and update the UI, changes to this will result in UI re-renders
const filesByID = new Map(
uniqueFiles.map((file) => [file.id, file]),
);
- //ref mirrow for using in the useCallbacks
filesByIDRef.current = filesByID;
const { points, latestFileId } =
await buildMapIndexPoints(uniqueFiles);
if (generation !== loadGenerationRef.current) return;
- //mapIndex has the SuperCluster Spatial Index
const mapIndex = buildMapIndex(points);
const latestPoint =
@@ -907,7 +680,6 @@ function useMapData(
error: null,
}));
- // Mark this collection as loaded
loadedCollectionRef.current = {
summaryId: currentSummaryId,
fileCount: currentFileCount,
@@ -931,7 +703,6 @@ function useMapData(
}));
onGenericError(e);
} finally {
- // Ensure we never leave the dialog stuck in a loading state
if (generation === loadGenerationRef.current) {
setState((prev) =>
prev.isLoading ? { ...prev, isLoading: false } : prev,
@@ -943,11 +714,6 @@ function useMapData(
void loadMapData();
}, [open, collectionSummary, files, onGenericError, queueThumbnailFetch]);
- /**
- * This function is used to update the map view, after a file has been
- * deleted by the user. The deleted file is removed from the mapPoints
- * and then a new mapIndex is built
- */
const removeFiles = useCallback((fileIDs: number[]) => {
if (!fileIDs.length) return;
setState((prev) => {
@@ -961,7 +727,6 @@ function useMapData(
const mapPoints = prev.mapPoints.filter(
(point) => !ids.has(point.fileId),
);
- //Rebuilding the mapIndex after removing the point from the mapPoints
const mapIndex = buildMapIndex(mapPoints);
let latestFileId = prev.latestFileId;
@@ -980,14 +745,9 @@ function useMapData(
});
}, []);
- /**
- * This function is used to update the visiblity of a file from
- * archive to unarchive or vice-versa.
- */
const updateFileVisibility = useCallback(
(file: EnteFile, visibility: ItemVisibility) => {
setState((prev) => {
- //If the file ID is not in the fileByID or the magicMetadata for the file doesn't exist then return prev state
if (!prev.filesByID.has(file.id)) return prev;
if (!file.magicMetadata) return prev;
@@ -1007,7 +767,6 @@ function useMapData(
let mapIndex = prev.mapIndex;
let latestFileId = prev.latestFileId;
- //If the file is not visible then removing it from the mapPoints and creating a new Supercluster Spatial Mapping
if (visibility !== ItemVisibility.visible) {
const filtered = prev.mapPoints.filter(
(point) => point.fileId !== file.id,
@@ -1020,7 +779,6 @@ function useMapData(
}
}
} else if (!prev.mapPoints.some((p) => p.fileId === file.id)) {
- //If the file was previously hidden then adding it back to the existing list.
const loc = fileLocation(file);
if (loc) {
const timestamp = fileCreationPhotoSortTime(file);
@@ -1034,7 +792,6 @@ function useMapData(
},
];
- //Recomputing the latest file, since there are possiblities of change
mapIndex = buildMapIndex(mapPoints);
const latestPoint =
latestFileId !== undefined
@@ -1046,7 +803,6 @@ function useMapData(
}
}
- //Recomputing the map center in case the latestFile has changed.
let mapCenter = prev.mapCenter;
if (!mapPoints.length) {
mapCenter = null;
@@ -1078,10 +834,6 @@ function useMapData(
return { ...state, removeFiles, updateFileVisibility, queueThumbnailFetch };
}
-/**
- * Manages favorite files state and handles favorite/visibility updates
- * Responsibility: Load user's favorites, toggle favorite status, update file visibility
- */
function useFavorites(
open: boolean,
user: ReturnType<typeof useCurrentUser>,
@@ -1094,16 +846,12 @@ function useFavorites(
visibility: ItemVisibility,
) => Promise<void>;
} {
- // Set to store the ids of files which are currenly favorited, if there is already an existing
- // sycnedFavoriteFileIDs list then using that as the inital value.
const [favoriteFileIDs, setFavoriteFileIDs] = useState<Set<number>>(
syncedFavoriteFileIDs ?? new Set(),
);
- //Set to store the IDs of the files which are in-flight for updation(favorite/unfavorite)
const [pendingFavoriteUpdates, setPendingFavoriteUpdates] = useState<
Set<number>
>(new Set());
- //Set to store the IDs of the files which are in-flight for updation(archive/unarchive)
const [pendingVisibilityUpdates, setPendingVisibilityUpdates] = useState<
Set<number>
>(new Set());
@@ -1111,17 +859,11 @@ function useFavorites(
useEffect(() => {
if (!open || !user) return;
- // If there already exist an syncedFavoriteFileIDs then using that as inital value.
if (syncedFavoriteFileIDs) {
setFavoriteFileIDs(syncedFavoriteFileIDs);
return;
}
- /**
- * Each collectionFile has a collectionID associated with them, checking whether
- * that id matches with the id of each collectionFiles and if so then adding it to the
- * favoriteFileIDs.
- */
const loadFavorites = async () => {
const collections = await savedCollections();
const collectionFiles = await savedCollectionFiles();
@@ -1146,7 +888,6 @@ function useFavorites(
void loadFavorites();
}, [open, syncedFavoriteFileIDs, user]);
- // Helper to add/remove from Set immutably - avoids recreating Set when unnecessary
const addToSet = useCallback((set: Set<number>, id: number) => {
if (set.has(id)) return set;
const next = new Set(set);
@@ -1181,16 +922,10 @@ function useFavorites(
return next ?? set;
}, []);
- // This function is triggered when if one visible shared/owned copy is toggled,
- // the equivalent copies update their star/pending UI together.
const favoriteEquivalentFileIDs = useCallback(
(file: EnteFile) => {
- // Getting the FileHashAndTypeKey of the file on which
- // the favorite toggle was triggered.
const key = favoriteFileHashAndTypeKey(file);
- // If there is no key we can't compute the equivalent files
- // so returned just the original file.
if (!key) return [file.id];
const isSharedSourceFile = file.ownerID != user?.id;
@@ -1199,16 +934,6 @@ function useFavorites(
const fileIDs = new Set([file.id]);
- /**
- * Looping through the favoriteEquivalenceFiles and for the files
- * whose key match with the file's key.
- *
- * - If it's a shared file then adding to fileIDs
- *
- * - If it's a owned fie then already favorited, then updating the flag and
- * and then adding it to the fileIDs.
- * - Else remembers the first owned equivalent ID
- */
for (const equivalentFile of favoriteEquivalenceFiles) {
if (favoriteFileHashAndTypeKey(equivalentFile) != key) {
continue;
@@ -1246,7 +971,6 @@ function useFavorites(
const fileID = file.id;
const fileIDs = favoriteEquivalentFileIDs(file);
- // Check favorite status at call time to avoid stale closure
const isFavorite = favoriteFileIDs.has(fileID);
setPendingFavoriteUpdates((prev) => addIDsToSet(prev, fileIDs));
@@ -1299,14 +1023,6 @@ function useFavorites(
};
}
-/**
- * Manages the lifecycle of the currently visible journey photos.
- *
- * Tracks the ordered list of visible photos and exposes a setter to update them.
- * It's the visiblePhotos that are being shown in the Sidebar to the left of the map
- *
- * @returns An object containing the visible photos array and setter.
- */
function useVisiblePhotos() {
const [visiblePhotos, setVisiblePhotos] = useState<MapPhotoPoint[]>([]);
const [isVisiblePhotosUpdating, setIsVisiblePhotosUpdating] =
@@ -1320,10 +1036,6 @@ function useVisiblePhotos() {
};
}
-/**
- * Creates a marker icon for individual photos (no badge)
- * Used only in CollectionMapDialog for consistent styling
- */
function createMarkerIcon(
imageSrc: string,
size: number,
@@ -1393,10 +1105,6 @@ function createMarkerIcon(
});
}
-/**
- * Creates a cluster icon with badge popping out of the container
- * Used only in CollectionMapDialog for cluster markers
- */
function createClusterIcon(
imageSrc: string,
size: number,
@@ -1501,18 +1209,6 @@ function createClusterIcon(
});
}
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-// ============================================================================
-// Main Component
-// ============================================================================
-
-/**
- * Main dialog component that displays a collection's photos on an interactive map
- * Responsibility: Coordinate all hooks, manage dialog state, render map layout or loading states
- */
export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
open,
onClose,
@@ -1622,7 +1318,6 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
[isFileViewerOpen],
);
- // Convert visible map photo points to EnteFiles for FileListWithViewer
const visibleFiles = useMemo(() => {
return visiblePhotos
.map((p) => filesByID.get(p.fileId))
@@ -1638,7 +1333,6 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
);
const visualFeedback = useMemo(() => onVisualFeedback, [onVisualFeedback]);
- // Empty selection state since we don't support selection in map view
const emptySelected = useMemo<SelectedState>(
() => ({
ownCount: 0,
@@ -1649,21 +1343,14 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
[activeCollection?.id, collectionSummary.id],
);
- /**
- * Since the map view actually doesn't support the selecting from the sidebar
- * adding a empty function, other wise the setSelection must be made optional
- * which is a more system wide change and unncessary.
- */
const noOpSetSelected = useCallback(() => {
- /* no-op */
+ // no-op
}, []);
const handleMarkTempDeleted = useCallback(
(files: EnteFile[]) => {
- //Triggering the gallery reducer's markTempDeleted
onMarkTempDeleted?.(files);
- //remove the deleted files from the visible photos which are shown in the sidebar
const idsToRemove = new Set(files.map((file) => file.id));
setVisiblePhotos((prev) =>
prev.filter((photo) => !idsToRemove.has(photo.fileId)),
@@ -1692,8 +1379,7 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
);
const body = useMemo(() => {
- // Only blank out the layout on the initial load; background reloads
- // keep the map (and any open file viewer) mounted.
+ // Background reloads keep the map and viewer mounted.
if (isLoading && !mapIndex) {
return (
<CenteredBox>
@@ -1712,7 +1398,6 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
);
}
- // Wait for map components to load (they're dynamically imported)
if (!mapComponents) {
return (
<CenteredBox>
@@ -1818,10 +1503,7 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
open={open}
onClose={onClose}
sx={{
- // When the FileViewer is open, lower this dialog's z-index below
- // PhotoSwipe's z-index (1199) so that FileViewer appears on top.
- // This avoids the visual glitch caused by closing/reopening the
- // dialog during transitions.
+ // Keep PhotoSwipe above the mounted dialog during transitions.
...(isFileViewerOpen && {
zIndex: (theme) =>
`calc(${theme.zIndex.drawer} - 2) !important`,
@@ -1844,14 +1526,6 @@ export const CollectionMapDialog: React.FC<CollectionMapDialogProps> = ({
);
};
-// ============================================================================
-// Layout Components
-// ============================================================================
-
-/**
- * Main layout container for map and sidebar
- * Responsibility: Position sidebar and map canvas side-by-side
- */
interface MapLayoutProps {
collectionSummary: CollectionSummary;
visiblePhotos: MapPhotoPoint[];
@@ -1975,14 +1649,6 @@ function MapLayout({
);
}
-// ============================================================================
-// Sidebar Components
-// ============================================================================
-
-/**
- * Sidebar displaying collection details and photo thumbnails using FileListWithViewer
- * Responsibility: Show collection cover, header, and file list with integrated viewer
- */
interface CollectionSidebarProps {
collectionSummary: CollectionSummary;
visibleCount: number;
@@ -2016,12 +1682,8 @@ interface CollectionSidebarProps {
setSelected: () => void;
}
-// Fixed height for the cover image container (px)
const COVER_IMAGE_HEIGHT = 320;
const MOBILE_SIDEBAR_HEIGHT = "50%";
-// Mobile has less padding: 8px top + 12px bottom + 2px margin = 22px
-// Desktop has more padding: 16px top + 16px bottom + 2px margin = 34px
-// Use desktop value for consistency in the virtualized list
const COVER_HEADER_HEIGHT = COVER_IMAGE_HEIGHT + 34;
function CollectionSidebar({
@@ -2061,7 +1723,6 @@ function CollectionSidebar({
const isDarkMode = theme.palette.mode === "dark";
const isMobile = useMediaQuery(theme.breakpoints.down("md"));
- // Get cover image: prioritize collection's coverFile, fallback to first photo
const coverFile = collectionSummary.coverFile;
const coverImageUrl = useMemo(() => {
const coverThumb = coverFile && thumbByFileID.get(coverFile.id);
@@ -2071,7 +1732,6 @@ function CollectionSidebar({
return fallbackId ? thumbByFileID.get(fallbackId) : undefined;
}, [coverFile, latestFileId, thumbByFileID]);
- // Create header component for FileListWithViewer (cover scrolls with content)
const coverHeader = useMemo(() => {
if (!shouldShowCover) return undefined;
return {
@@ -2094,17 +1754,14 @@ function CollectionSidebar({
onClose,
]);
- // Handle scroll events from the file list
const handleScroll = useCallback((offset: number) => {
setScrollOffset(offset);
}, []);
- // Handle visible date changes from the file list
const handleVisibleDateChange = useCallback((date: string | undefined) => {
setCurrentDate(date);
}, []);
- // Only show sticky date after scrolling past the cover header, or always for "All"
const showStickyHeader =
!shouldShowCover ||
(scrollOffset > COVER_HEADER_HEIGHT && !!currentDate);
@@ -2233,14 +1890,6 @@ function CollectionSidebar({
);
}
-// ============================================================================
-// Map Components
-// ============================================================================
-
-/**
- * Renders the Leaflet map with markers, clusters, and controls
- * Responsibility: Display interactive map with photo markers and handle viewport changes
- */
interface MapCanvasProps {
mapComponents: MapComponents;
mapCenter: [number, number];
@@ -2304,10 +1953,6 @@ const MapCanvas = React.memo(function MapCanvas({
);
});
-/**
- * Floating map control buttons (open in Maps, zoom in/out)
- * Responsibility: Provide map navigation and external link controls
- */
interface MapControlsProps {
useMap: typeof import("react-leaflet").useMap;
}
@@ -2332,7 +1977,6 @@ const MapControls = React.memo(function MapControls({
return (
<>
- {/* Zoom controls: top left on mobile, bottom right on desktop */}
<Stack
spacing={1}
sx={(theme) => ({
@@ -2354,7 +1998,6 @@ const MapControls = React.memo(function MapControls({
<FloatingIconButton onClick={handleZoomOut}>
<RemoveIcon />
</FloatingIconButton>
- {/* Location button: hidden on mobile, shown in stack on desktop */}
<FloatingIconButton
onClick={handleOpenInMaps}
sx={(theme) => ({
@@ -2366,7 +2009,6 @@ const MapControls = React.memo(function MapControls({
</FloatingIconButton>
</Stack>
- {/* Location button: top right on mobile only */}
<FloatingIconButton
onClick={handleOpenInMaps}
sx={(theme) => ({
@@ -2664,14 +2306,6 @@ const MapClusters = React.memo(function MapClusters({
);
});
-// ============================================================================
-// UI Components
-// ============================================================================
-
-/**
- * Styled floating action button with consistent styling
- * Responsibility: Provide consistent button styling for map controls
- */
const FloatingIconButton: React.FC<IconButtonProps> = ({ sx, ...props }) => {
const baseSx = {
bgcolor: (theme: {
@@ -2701,10 +2335,6 @@ const FloatingIconButton: React.FC<IconButtonProps> = ({ sx, ...props }) => {
return <IconButton {...props} sx={mergedSx} />;
};
-/**
- * Centered container for loading/error states with optional close button
- * Responsibility: Display centered content like loading spinners or error messages
- */
interface CenteredBoxProps extends React.PropsWithChildren {
onClose?: () => void;
closeLabel?: string;
@@ -2727,22 +2357,10 @@ function CenteredBox({ children, onClose, closeLabel }: CenteredBoxProps) {
);
}
-/**
- * Empty state placeholder for when no photos are visible
- * Responsibility: Display empty state message when no photos match filters
- */
function EmptyState({ children }: React.PropsWithChildren) {
return <EmptyStateContainer>{children}</EmptyStateContainer>;
}
-// ============================================================================
-// Map Cover Component
-// ============================================================================
-
-/**
- * Hero image cover for the collection with title and memory count
- * Responsibility: Display collection cover image, name, and visible memory count
- */
interface MapCoverProps {
name: string;
coverImageUrl: string | undefined;
@@ -2857,10 +2475,6 @@ const CoverSubtitle = styled(Typography)({
fontWeight: "500",
});
-// ============================================================================
-// Sidebar Styled Components
-// ============================================================================
-
const SidebarWrapper = styled(Box)(({ theme }) => ({
position: "absolute",
left: 0,
diff --git a/web/apps/photos/src/components/FileList.tsx b/web/apps/photos/src/components/FileList.tsx
index b38768d044..d4e207d0d4 100644
--- a/web/apps/photos/src/components/FileList.tsx
+++ b/web/apps/photos/src/components/FileList.tsx
@@ -59,232 +59,76 @@ import {
type ListChildComponentProps,
} from "react-window";
-/**
- * A component with an explicit height suitable for being plugged in as the
- * {@link header} or {@link footer} of the {@link FileList}.
- */
export interface FileListHeaderOrFooter {
- /**
- * The component itself.
- */
component: React.ReactNode;
- /**
- * The height of the component (in px).
- */
height: number;
- /**
- * By default, all items in the {@link FileList}, including headers and
- * footers injected using this type, get an inline margin.
- *
- * Set this property to `true` to omit this default margin, and instead
- * have the component extend to the container's edges.
- */
extendToInlineEdges?: boolean;
}
-/**
- * Data needed to render each row in the variable size list that comprises the
- * file list.
- */
type FileListItem =
| {
type: "file";
- /**
- * The height of the row that will render this item.
- */
height: number;
- /**
- * Groups of items that are shown in the row.
- *
- * Each group spans multiple columns (the number of columns being given by
- * the length of {@link annotatedFiles} or the {@link span}). Groups are
- * separated by gaps.
- */
groups: {
- /**
- * The annotated files in this group.
- */
annotatedFiles: FileListAnnotatedFile[];
- /**
- * The index of the first annotated file in the component's global list
- * of annotated files.
- */
annotatedFilesStartIndex: number;
}[];
}
| {
type: "date";
height: number;
- groups: {
- /**
- * The date string to show.
- */
- date: string;
- /**
- * The number of columns to span.
- */
- dateSpan: number;
- }[];
+ groups: { date: string; dateSpan: number }[];
}
| {
type: "span";
height: number;
- /**
- * The React component that is the rendered representation of the item.
- */
component: React.ReactNode;
extendToInlineEdges?: boolean;
};
export interface FileListAnnotatedFile {
file: EnteFile;
- /**
- * The date string using with the associated {@link file} should be shown in
- * the timeline.
- *
- * [Note: Timeline date string]
- *
- * The timeline date string is a formatted date string under which a
- * particular file should be grouped in the gallery listing. e.g. "Today",
- * "Yesterday", "Fri, 21 Feb" etc.
- *
- * All files which have the same timelineDateString will be grouped under a
- * single section in the gallery listing, prefixed by the timelineDateString
- * itself, and a checkbox to select all files on that date.
- */
timelineDateString: string;
}
-/**
- * A file augmented with the date when it will be permanently deleted.
- *
- * See: [Note: Files in trash pseudo collection have deleteBy]
- */
-export type EnteTrashFile = EnteFile & {
- /**
- * Timestamp (epoch microseconds) when the trash item (and its corresponding
- * {@link EnteFile}) will be permanently deleted.
- */
- deleteBy?: number;
-};
+// deleteBy is an epoch-microsecond timestamp.
+export type EnteTrashFile = EnteFile & { deleteBy?: number };
export interface FileListProps {
- /** The height we should occupy (needed since the list is virtualized). */
height: number;
- /** The width we should occupy.*/
width: number;
- /**
- * Optional border radius to apply to the scrollable list container.
- */
listBorderRadius?: string;
- /**
- * The files to show, annotated with cached precomputed properties that are
- * frequently needed by the {@link FileList}.
- */
annotatedFiles: FileListAnnotatedFile[];
mode?: GalleryBarMode;
- /**
- * This is an experimental prop, to see if we can merge the separate
- * "isInSearchMode" state kept by the gallery to be instead provided as a
- * another mode in which the gallery operates.
- */
modePlus?: GalleryBarMode | "search";
- /**
- * An optional component shown before all the items in the list.
- *
- * It is not sticky, and scrolls along with the content of the list.
- */
header?: FileListHeaderOrFooter;
- /**
- * An optional component shown after all the items in the list.
- *
- * It is not sticky, and scrolls along with the content of the list.
- */
footer?: FileListHeaderOrFooter;
- /**
- * The logged in user, if any.
- */
user?: LocalUser;
- /**
- * If `true`, then the default behaviour of grouping files by their date is
- * suppressed.
- *
- * This behaviour is used when showing magic search results.
- */
disableGrouping?: boolean;
- /**
- * If `true`, then the user can select files in the listing by clicking on
- * their thumbnails (and other range selection mechanisms).
- */
enableSelect?: boolean;
setSelected: (
selected: SelectedState | ((selected: SelectedState) => SelectedState),
) => void;
selected: SelectedState;
- /** This will be set if mode is not "people". */
activeCollectionID: number;
- /** This will be set if mode is "people". */
activePersonID?: string | undefined;
- /**
- * File IDs of all the files that the user has marked as a favorite.
- */
favoriteFileIDs?: Set<number>;
- /**
- * A map from known Ente user IDs to their emails.
- */
emailByUserID?: Map<number, string>;
- /**
- * Called when the user activates the thumbnail at the given {@link index}.
- *
- * This corresponding file would be at the corresponding index of
- * {@link annotatedFiles}.
- */
onItemClick: (index: number) => void;
- /**
- * Called when the list scrolls, providing the current scroll offset.
- */
onScroll?: (scrollOffset: number) => void;
- /**
- * Called when the visible date at the top of the viewport changes.
- */
onVisibleDateChange?: (date: string | undefined) => void;
- /**
- * The collection summary for the current view.
- *
- * Used to determine available context menu actions.
- */
collectionSummary?: CollectionSummary;
- /**
- * Called when a context menu action is triggered on a file.
- *
- * @param action The action that was triggered.
- */
onContextMenuAction?: (
action: FileContextAction,
targetFile?: EnteFile,
meta?: { isEphemeralSingleSelection: boolean },
) => void;
- /**
- * Whether to show the "Add Person" action in the context menu.
- */
showAddPersonAction?: boolean;
- /**
- * Whether to show the "Edit Location" action in the context menu.
- */
showEditLocationAction?: boolean;
- /**
- * Called when the context menu opens or closes.
- */
onContextMenuOpenChange?: (open: boolean) => void;
- /**
- * Hide selection visuals/interactions while keeping selection data.
- */
suppressSelectionUI?: boolean;
}
-/**
- * A virtualized list of files, each represented by their thumbnail.
- */
export const FileList: React.FC<FileListProps> = ({
height,
width,
@@ -321,31 +165,18 @@ export const FileList: React.FC<FileListProps> = ({
);
const [hoverIndex, setHoverIndex] = useState<number | undefined>(undefined);
const [isShiftKeyPressed, setIsShiftKeyPressed] = useState(false);
- // Timeline date strings for which all photos have been selected.
- //
- // See: [Note: Timeline date string]
const [checkedTimelineDateStrings, setCheckedTimelineDateStrings] =
useState(new Set<string>());
- // Show back-to-top button when scrolled past threshold
const [showBackToTop, setShowBackToTop] = useState(false);
- // Context menu state
const [contextMenu, setContextMenu] = useState<{
position: ContextMenuPosition;
file: EnteFile;
fileIndex: number;
} | null>(null);
- // Track selection state before right-click modified it.
- // If there are already 3 files explicitly selected via checkmarks,
- // right-clicking an unselected item will store the previous selections
- // in this ref and temporarily select only the right-clicked file.
- // If no action is taken from the context menu, the previous selection
- // is restored when the menu closes.
+ // Right-click temporarily replaces selection; restore it if no action runs.
const previousSelectionRef = useRef<SelectedState | null>(null);
- // Track whether an action was taken from the context menu.
- // This ref works in conjunction with previousSelectionRef: if an action
- // is taken, the previous selection is not reverted when the context menu closes.
const contextMenuActionTakenRef = useRef(false);
const listRef = useRef<VariableSizeList | null>(null);
@@ -357,14 +188,7 @@ export const FileList: React.FC<FileListProps> = ({
);
useEffect(() => {
- // Since width and height are dependencies, there might be too many
- // updates to the list during a resize. The list computation too, while
- // fast, is non-trivial.
- //
- // To avoid these issues, the we use `useDeferredValue`: if it gets
- // another update when processing one, React will restart the background
- // rerender from scratch.
-
+ // Defer resize-heavy list rebuilds so React can discard stale renders.
let items: FileListItem[] = [];
if (header) items.push(asFullSpanFileListItem(header));
@@ -387,8 +211,6 @@ export const FileList: React.FC<FileListProps> = ({
),
);
} else {
- // A running counter of files that have been pushed into items, and
- // a function to push them (incrementing the counter).
let fileIndex = 0;
const createFileItem = (splits: FileListAnnotatedFile[][]) =>
({
@@ -406,8 +228,6 @@ export const FileList: React.FC<FileListProps> = ({
const pushItemsFromSplits = (splits: FileListAnnotatedFile[][]) => {
if (splits.length > 1) {
- // If we get here, the combined number of files across
- // splits is less than the number of columns.
items.push({
height: dateListItemHeight,
type: "date",
@@ -418,8 +238,6 @@ export const FileList: React.FC<FileListProps> = ({
});
items.push(createFileItem(splits));
} else {
- // A single group of files, but the number of such files
- // might be more than what fits a single row.
items.push({
height: dateListItemHeight,
type: "date",
@@ -446,7 +264,6 @@ export const FileList: React.FC<FileListProps> = ({
);
const incomingColumns = split.length;
- // Check if the files in this split can be added to same row.
if (
!isSmallerLayout &&
filledColumns +
@@ -508,7 +325,6 @@ export const FileList: React.FC<FileListProps> = ({
]);
useEffect(() => {
- // Refresh list
listRef.current?.resetAfterIndex(0);
}, [items]);
@@ -517,28 +333,21 @@ export const FileList: React.FC<FileListProps> = ({
(af) => !selected[af.file.id],
);
- // Get dates of files which were manually unselected.
const unselectedDates = new Set(
notSelectedFiles.map((af) => af.timelineDateString),
);
- // Get files which were manually selected.
const localSelectedFiles = annotatedFiles.filter(
(af) => !unselectedDates.has(af.timelineDateString),
);
- // Get dates of files which were manually selected.
const localSelectedDates = new Set(
localSelectedFiles.map((af) => af.timelineDateString),
);
setCheckedTimelineDateStrings((prev) => {
const checked = new Set(prev);
- // Uncheck the "Select all" checkbox if any of the files on the date
- // is unselected.
unselectedDates.forEach((date) => checked.delete(date));
- // Check the "Select all" checkbox if all of the files on a date are
- // selected.
localSelectedDates.forEach((date) => checked.add(date));
return checked;
});
@@ -569,7 +378,6 @@ export const FileList: React.FC<FileListProps> = ({
}
setCheckedTimelineDateStrings(next);
- // All files on a checked/unchecked day.
const filesOnADay = annotatedFiles.filter(
(af) => af.timelineDateString === date,
);
@@ -674,8 +482,6 @@ export const FileList: React.FC<FileListProps> = ({
return count;
}, [favoriteFileIDs, selected]);
- // Compute available context menu actions based on stable context and
- // the favorite status of the current selection (for toggling).
const contextMenuActions = useMemo(() => {
if (!onContextMenuAction || !contextMenu) return [];
const isTemporarySingleSelection =
@@ -729,7 +535,6 @@ export const FileList: React.FC<FileListProps> = ({
selected.count,
]);
- // Handle context menu open
const handleContextMenu = useCallback(
(event: React.MouseEvent, file: EnteFile, fileIndex: number) => {
if (!onContextMenuAction) return;
@@ -737,15 +542,11 @@ export const FileList: React.FC<FileListProps> = ({
event.preventDefault();
event.stopPropagation();
- // Reset tracking for this menu open.
previousSelectionRef.current = null;
contextMenuActionTakenRef.current = false;
- // Handle selection behavior on right-click
if (!selected[file.id]) {
- // Store current selection before replacing it
previousSelectionRef.current = { ...selected };
- // File not selected: clear selection and select only this file
const isOwnFile = file.ownerID === user?.id;
const context =
mode === "people" && activePersonID
@@ -765,7 +566,6 @@ export const FileList: React.FC<FileListProps> = ({
context,
});
}
- // If file is already selected, keep current multi-selection
setContextMenu({
position: { top: event.clientY, left: event.clientX },
@@ -786,9 +586,8 @@ export const FileList: React.FC<FileListProps> = ({
],
);
- // Handle context menu close
const handleContextMenuClose = useCallback(() => {
- // Defer restore so a menu-item click can mark the close as action-driven.
+ // Menu close precedes item click, so restoration must wait a microtask.
void Promise.resolve().then(() => {
if (
!contextMenuActionTakenRef.current &&
@@ -953,17 +752,14 @@ export const FileList: React.FC<FileListProps> = ({
}
}, []);
- // Track the last reported date to avoid unnecessary callbacks
const lastVisibleDateRef = useRef<string | undefined>(undefined);
const handleScroll = useCallback(
({ scrollOffset }: { scrollOffset: number }) => {
onScroll?.(scrollOffset);
- // Show back-to-top button when scrolled past threshold
setShowBackToTop(scrollOffset > 500);
- // Calculate which date is visible at the current scroll position
if (onVisibleDateChange && items.length > 0) {
let cumulativeHeight = 0;
let currentDate: string | undefined;
@@ -973,13 +769,11 @@ export const FileList: React.FC<FileListProps> = ({
currentDate = item.groups[0]?.date;
}
cumulativeHeight += item.height;
- // Found the item that contains the scroll position
if (cumulativeHeight > scrollOffset) {
break;
}
}
- // Only call callback if date changed
if (currentDate !== lastVisibleDateRef.current) {
lastVisibleDateRef.current = currentDate;
onVisibleDateChange(currentDate);
@@ -997,11 +791,9 @@ export const FileList: React.FC<FileListProps> = ({
return <></>;
}
- // The old, mode unaware, behaviour.
+ // A new key resets virtualization state when the view changes.
let key = `${activeCollectionID}`;
if (modePlus) {
- // If the new experimental modePlus prop is provided, use it to derive a
- // mode specific key.
if (modePlus == "search") {
key = "search";
} else if (modePlus == "people") {
@@ -1054,10 +846,6 @@ export const FileList: React.FC<FileListProps> = ({
);
};
-/**
- * Return a new array of splits, each split containing {@link annotatedFiles}
- * which have the same {@link timelineDateString}.
- */
const splitByDate = (annotatedFiles: FileListAnnotatedFile[]) =>
annotatedFiles.reduce(
(splits, annotatedFile) => (
@@ -1070,11 +858,6 @@ const splitByDate = (annotatedFiles: FileListAnnotatedFile[]) =>
new Array<FileListAnnotatedFile[]>(),
);
-/**
- * For each element of {@link xs}, obtain an array by applying {@link f},
- * then obtain a gap element by applying {@link g}. Return a flattened array
- * containing all of these, except the trailing gap.
- */
const intersperseWithGaps = <T, U>(
xs: T[],
f: (x: T) => U[],
@@ -1084,9 +867,6 @@ const intersperseWithGaps = <T, U>(
return ys.slice(0, ys.length - 1);
};
-/**
- * A list item container that spans the full width.
- */
const FullSpanListItem = styled("div")`
display: flex;
align-items: center;
@@ -1097,9 +877,6 @@ const NoFilesListItem = styled(FullSpanListItem)`
justify-content: center;
`;
-/**
- * Floating button to scroll back to the top of the file list.
- */
const BackToTopButton = styled(Fab)(({ theme }) => ({
position: "absolute",
bottom: 24,
@@ -1111,10 +888,6 @@ const BackToTopButton = styled(Fab)(({ theme }) => ({
[theme.breakpoints.down("sm")]: { display: "none" },
}));
-/**
- * Convert a {@link FileListHeaderOrFooter} into a {@link FileListItem}
- * that spans the entire width available to the row.
- */
const asFullSpanFileListItem = ({
component,
...rest
@@ -1124,18 +897,12 @@ const asFullSpanFileListItem = ({
component: <FullSpanListItem>{component}</FullSpanListItem>,
});
-/**
- * An grid item, spanning {@link span} columns.
- */
const GridSpanListItem = styled("div")<{ span: number }>`
grid-column: span ${({ span }) => span};
display: flex;
align-items: center;
`;
-/**
- * The fixed height (in px) of {@link DateListItem}.
- */
const dateListItemHeight = 48;
const DateListItem = styled(GridSpanListItem)(
@@ -1304,7 +1071,7 @@ const FileThumbnail: React.FC<FileThumbnailProps> = ({
}
};
- // See: [Note: Files in trash pseudo collection have deleteBy]
+ // Trash entries carry deleteBy despite the EnteFile type.
const deleteBy =
activeCollectionID == PseudoCollectionID.trash &&
(file as EnteTrashFile).deleteBy;
@@ -1407,6 +1174,7 @@ const FileThumbnail_ = styled("div")<{ disabled: boolean }>`
border-radius: 4px;
`;
+// Safari needs explicit display and positioning for these pseudo-elements.
const Check = styled("input")<{ $active: boolean }>(
({ theme, $active }) => `
appearance: none;
@@ -1427,19 +1195,19 @@ const Check = styled("input")<{ $active: boolean }>(
&::before {
content: "";
- display: block; /* Critical for Safari */
+ display: block;
width: 19px;
height: 19px;
background-color: #ddd;
border-radius: 50%;
margin: 6px;
transition: background-color 0.3s ease, opacity 0.3s ease;
- position: relative; /* Important for Safari */
+ position: relative;
}
&::after {
content: "";
- display: block; /* Critical for Safari */
+ display: block;
position: absolute;
top: 50%;
left: 50%;
@@ -1452,10 +1220,7 @@ const Check = styled("input")<{ $active: boolean }>(
transform-origin: center;
}
- /* Default state - hide both */
visibility: hidden;
-
- /* When $active - show both with reduced opacity */
${
$active &&
`
@@ -1464,13 +1229,11 @@ const Check = styled("input")<{ $active: boolean }>(
`
};
- /* Hover state - show both */
&:hover {
visibility: visible;
opacity: 0.7;
}
- /* Checked state - show both with full opacity and colored */
&:checked {
visibility: visible;
opacity: 1 !important;
@@ -1499,10 +1262,6 @@ const HoverOverlay = styled("div")<{ checked: boolean }>`
"background:linear-gradient(rgba(0, 0, 0, 0.2), rgba(0, 0, 0, 0))"};
`;
-/**
- * An overlay showing the avatars of the person who shared the item, at the top
- * right.
- */
const AvatarOverlay = styled(Overlay)`
display: flex;
justify-content: flex-end;
@@ -1510,9 +1269,6 @@ const AvatarOverlay = styled(Overlay)`
padding: 5px;
`;
-/**
- * An overlay showing the favorite icon at bottom left.
- */
const FavoriteOverlay = styled(Overlay)`
display: flex;
justify-content: flex-start;
@@ -1522,10 +1278,6 @@ const FavoriteOverlay = styled(Overlay)`
opacity: 0.6;
`;
-/**
- * An overlay with a gradient, showing the file type indicator (e.g. live photo,
- * video) at the bottom right.
- */
const FileTypeIndicatorOverlay = styled(Overlay)`
display: flex;
justify-content: flex-end;
@@ -1576,18 +1328,9 @@ const VideoDurationOverlay: React.FC<VideoDurationOverlayProps> = ({
</FileTypeIndicatorOverlay>
);
-/**
- * Return `true` if the owner or uploader name avatar indicator should be shown
- * for the given {@link file}.
- */
const shouldShowAvatar = (file: EnteFile, user: LocalUser | undefined) => {
- // Public albums app.
if (!user) return false;
- // A file shared with the user.
if (file.ownerID != user.id) return true;
- // A public collected file (i.e. a file owned by the user, uploaded by an
- // named guest via a public collect link)
if (file.pubMagicMetadata?.data.uploaderName) return true;
- // Regular file.
return false;
};
diff --git a/web/apps/photos/src/components/SearchBar.tsx b/web/apps/photos/src/components/SearchBar.tsx
index e9f007e50c..6811806174 100644
--- a/web/apps/photos/src/components/SearchBar.tsx
+++ b/web/apps/photos/src/components/SearchBar.tsx
@@ -55,63 +55,16 @@ import {
import AsyncSelect from "react-select/async";
export interface SearchBarProps {
- /**
- * [Note: "Search mode"]
- *
- * On mobile sized screens, normally the search input areas is not
- * displayed. Clicking the search icon enters the "search mode", where we
- * show the search input area.
- *
- * On other screens, the search input is always shown even if we are not in
- * search mode.
- *
- * When we're in search mode,
- *
- * 1. Other icons from the navbar are hidden.
- * 2. Next to the search input there is a cancel button to exit search mode.
- */
isInSearchMode: boolean;
- /**
- * Invoked when the user wants to enter "search mode".
- *
- * This scenario only arises when the search bar is in the mobile device
- * sized configuration, where the user needs to tap the search icon to enter
- * the search mode.
- */
onShowSearchInput: () => void;
- /**
- * Set or clear the selected {@link SearchOption}.
- */
onSelectSearchOption: (
o: SearchOption | undefined,
options?: { shouldExitSearchMode?: boolean },
) => void;
- /**
- * Called when the user selects the generic "People" header in the empty
- * state view.
- */
onSelectPeople: () => void;
- /**
- * Called when the user selects a person shown in the empty state view.
- */
onSelectPerson: (personID: string) => void;
}
-/**
- * The search bar is a styled "select" element that allow the user to type in
- * the attached input field, and shows a list of matching suggestions in a
- * dropdown.
- *
- * When the search input is empty, it shows some general information in the
- * dropdown instead (e.g. the ML indexing status).
- *
- * When the search input is not empty, it shows these {@link SearchSuggestion}s.
- * Alongside each suggestion is shows a count of matching files, and some
- * previews.
- *
- * Selecting one of the these suggestions causes the gallery to shows a filtered
- * list of files that match that suggestion.
- */
export const SearchBar: React.FC<SearchBarProps> = ({
isInSearchMode,
onShowSearchInput,
@@ -131,21 +84,12 @@ export const SearchBar: React.FC<SearchBarProps> = ({
};
interface MobileSearchAreaProps {
- /** Called when the user presses the search button. */
onSearch: () => void;
}
const MobileSearchArea: React.FC<MobileSearchAreaProps> = ({ onSearch }) => (
<Stack direction="row" sx={{ alignItems: "center" }}>
- <EnteLogoBox
- sx={{
- // Move to the center.
- mx: "auto",
- // Offset on the left by the visual size of the search icon to
- // make it look visually centered.
- pl: "24px",
- }}
- >
+ <EnteLogoBox sx={{ mx: "auto", pl: "24px" }}>
<EnteLogo height={15} />
</EnteLogoBox>
<IconButton onClick={onSearch}>
@@ -160,18 +104,11 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
onSelectPeople,
onSelectPerson,
}) => {
- // A ref to the top level Select.
const selectRef = useRef<SelectInstance<SearchOption> | null>(null);
- // Subscribe to people state so that we re-render when people data arrives.
- // This is needed because shouldShowEmptyState reads peopleStateSnapshot().
+ // Subscribe even though reads happen through peopleStateSnapshot().
usePeopleStateSnapshot();
- // The currently selected option.
- //
- // We need to use `null` instead of `undefined` to indicate missing values,
- // because using `undefined` instead moves the Select from being a controlled
- // component to an uncontrolled component.
+ // undefined makes react-select switch from controlled to uncontrolled.
const [value, setValue] = useState<SearchOption | null>(null);
- // The contents of the input field associated with the select.
const [inputValue, setInputValue] = useState("");
const [isFocused, setIsFocused] = useState(false);
@@ -180,10 +117,8 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
const styles = useMemo(() => createSelectStyles(theme), [theme]);
const components = useMemo(() => ({ Control, Input, Option }), []);
- // Handle ctrl+K keyboard shortcut to focus search
useEffect(() => {
const handleKeyDown = (event: KeyboardEvent) => {
- // Check for ctrl+K (cmd+K on macOS)
if ((event.metaKey || event.ctrlKey) && event.key === "k") {
event.preventDefault();
selectRef.current?.focus();
@@ -196,8 +131,6 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
const handleChange = (value: SearchOption | null) => {
const type = value?.suggestion.type;
- // Collection and people suggestions are handled differently - our
- // caller will switch to the corresponding view, dismissing search.
if (
type == "collection" ||
type == "person" ||
@@ -210,21 +143,11 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
setInputValue(value?.suggestion.label ?? "");
}
- // Let our parent know the selection was changed.
- // When selecting an option, we should exit search mode if needed.
onSelectSearchOption(nullToUndefined(value), {
shouldExitSearchMode: true,
});
- // The Select has a blurInputOnSelect prop, but that makes the input
- // field lose focus, not the entire menu (e.g. when pressing twice).
- //
- // We anyways need the ref so that we can blur on selecting a person
- // from the default options. So also use it to blur the entire Select
- // (including the menu) when the user selects an option.
- //
- // Only blur when an actual option was selected, not when clearing
- // (e.g., via backspace on empty input).
+ // blurInputOnSelect leaves react-select's menu open.
if (value) selectRef.current?.blur();
};
@@ -232,11 +155,9 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
if (actionMeta.action == "input-change") {
setInputValue(value);
- // If the input is cleared, also clear the selected value.
if (value === "") {
setValue(null);
setInputValue("");
- // Notify parent but don't exit search mode on mobile
onSelectSearchOption(undefined, {
shouldExitSearchMode: false,
});
@@ -245,14 +166,11 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
};
const resetSearch = () => {
- // Dismiss the search menu if it is open.
selectRef.current?.blur();
- // Clear all our state.
setValue(null);
setInputValue("");
- // Let our parent know and exit search mode entirely.
onSelectSearchOption(undefined, { shouldExitSearchMode: true });
};
@@ -268,9 +186,7 @@ const SearchInput: React.FC<Omit<SearchBarProps, "onShowSearchInput">> = ({
const handleFocus = () => {
setIsFocused(true);
- // A workaround to show the suggestions again for the current non-empty
- // search string if the user focuses back on the input field after
- // moving focus elsewhere.
+ // Refocusing needs an input nudge to reopen unchanged suggestions.
if (inputValue) {
selectRef.current?.onInputChange(inputValue, {
action: "set-value",
@@ -353,8 +269,6 @@ const loadOptions = pDebounce(async (input: string) => {
return [...photoOptions, ...sidebarActions];
}, 250);
-// const loadOptions = pDebounce(searchOptionsForString, 250);
-
const createSelectStyles = (
theme: Theme,
): StylesConfig<SearchOption, false> => ({
@@ -376,10 +290,7 @@ const createSelectStyles = (
}),
menu: (style) => ({
...style,
- // Suppress the default margin at the top.
marginTop: "1px",
- // Give an opaque and elevated surface color to the menu to override the
- // default (transparent).
backgroundColor: theme.vars.palette.background.elevatedPaper,
}),
option: (style, { isFocused }) => ({
@@ -387,7 +298,6 @@ const createSelectStyles = (
padding: 0,
backgroundColor: "transparent !important",
"& :hover": { cursor: "pointer" },
- // Elevate the focused option further.
"& .option-contents": isFocused
? { backgroundColor: theme.vars.palette.fill.fainter }
: {},
@@ -399,14 +309,12 @@ const createSelectStyles = (
whiteSpace: "nowrap",
overflowX: "hidden",
}),
- // Hide some things we don't need.
dropdownIndicator: (style) => ({ ...style, display: "none" }),
indicatorSeparator: (style) => ({ ...style, display: "none" }),
clearIndicator: (style) => ({ ...style, display: "none" }),
});
const Control = ({ children, ...props }: ControlProps<SearchOption, false>) => {
- // The shortcut UI element will be shown once the search bar supports searching the settings as well.
const isMac =
typeof navigator !== "undefined" &&
navigator.userAgent.toUpperCase().includes("MAC");
@@ -417,19 +325,10 @@ const Control = ({ children, ...props }: ControlProps<SearchOption, false>) => {
return (
<SelectComponents.Control {...props}>
- <Stack
- direction="row"
- sx={{
- alignItems: "center",
- // Fill the entire control (the control uses display flex).
- flex: 1,
- }}
- >
+ <Stack direction="row" sx={{ alignItems: "center", flex: 1 }}>
<Box
sx={{
display: "inline-flex",
- // Match the default padding of the ValueContainer to make
- // the icon look properly spaced and aligned.
pl: "8px",
color: "stroke.muted",
}}
@@ -481,34 +380,16 @@ const iconForOption = (option: SearchOption | undefined) => {
}
};
-/**
- * A custom input for react-select that is always visible.
- *
- * This is a workaround to allow the search string to be always displayed, and
- * editable, even after the user has moved focus away from it.
- */
+// Keep the search text visible after react-select loses focus.
const Input: React.FC<InputProps<SearchOption, false>> = (props) => (
<SelectComponents.Input {...props} isHidden={false} />
);
-/**
- * A preflight check for whether or not we should show the EmptyState.
- *
- * react-select seems to only suppress showing anything at all in the menu if we
- * return `null` from the function passed to `noOptionsMessage`. Returning
- * `false`, or returning `null` from the EmptyState itself doesn't work and
- * causes a empty div to be shown instead.
- */
+// noOptionsMessage must return null or react-select leaves an empty menu div.
const shouldShowEmptyState = (inputValue: string) => {
- // Don't show empty state if the user has entered search input.
if (inputValue) return false;
- // Don't show empty state if there is no ML related information AND we're
- // not processing videos.
-
if (!isMLSupported && !isHLSGenerationSupported) {
- // Neither of ML or HLS generation is supported on current client. This
- // is the code path for web.
return false;
}
@@ -521,8 +402,6 @@ const shouldShowEmptyState = (inputValue: string) => {
vpStatus?.enabled && vpStatus.status == "processing";
if (isMLInactive && !isVideoProcessing) {
- // ML is inactive AND video processing is not happening.
- // Only show empty state if there are people to display.
const people = peopleStateSnapshot()?.visiblePeople;
const hasPeople = people && people.length > 0;
if (!hasPeople) {
@@ -530,14 +409,9 @@ const shouldShowEmptyState = (inputValue: string) => {
}
}
- // Show it otherwise.
return true;
};
-/**
- * The view shown in the menu area when the user has not typed anything in the
- * search box.
- */
const EmptyState: React.FC<
Pick<SearchBarProps, "onSelectPeople" | "onSelectPerson">
> = ({ onSelectPeople, onSelectPerson }) => {
@@ -550,7 +424,6 @@ const EmptyState: React.FC<
case undefined:
case "disabled":
case "done":
- // If ML is not running, see if video processing is.
if (vpStatus?.enabled && vpStatus.status == "processing") {
label = t("processing_videos_status");
}
@@ -569,7 +442,6 @@ const EmptyState: React.FC<
break;
}
- // If there's nothing to show (no people and no status label), return empty.
const hasPeople = people && people.length > 0;
if (!hasPeople && !label) {
return <></>;
diff --git a/web/apps/photos/src/components/Upload.tsx b/web/apps/photos/src/components/Upload.tsx
index 0ade8c7ae5..9b0ce645f4 100644
--- a/web/apps/photos/src/components/Upload.tsx
+++ b/web/apps/photos/src/components/Upload.tsx
@@ -94,7 +94,6 @@ import { t } from "i18next";
import React, { useCallback, useEffect, useRef, useState } from "react";
interface UploadProps {
- /** The logged in user, if any. */
user?: LocalUser;
isFirstUpload?: boolean;
uploadTypeSelectorView: boolean;
@@ -105,53 +104,15 @@ interface UploadProps {
setLoading: (loading: boolean) => void;
setShouldDisableDropzone: (value: boolean) => void;
showCollectionSelector?: () => void;
- /**
- * Called when the uploader (or the file watcher) wants to perform a full
- * remote pull.
- *
- * See also {@link onRemoteFilesPull}.
- */
onRemotePull: (opts?: RemotePullOpts) => Promise<void>;
- /**
- * Called when an action in the uploader requires us to first pull the
- * latest files and collections from remote.
- *
- * See: [Note: Full remote pull vs files pull]
- *
- * Specifically, this is used prior to creating a new album, to obtain
- * (potential) existing albums from remote so that they can be matched by
- * name if needed.
- */
onRemoteFilesPull: () => Promise<void>;
- /**
- * Show the collection selector with the given {@link attributes}.
- */
onOpenCollectionSelector?: (
attributes: CollectionSelectorAttributes,
) => void;
- /**
- * Close the collection selector if it is open.
- */
onCloseCollectionSelector?: () => void;
- /**
- * Callback invoked when a file is uploaded.
- *
- * @param file The newly uploaded file.
- */
onUploadFile: (file: EnteFile) => void;
- /** Called when the plan selection modal should be shown. */
onShowPlanSelector?: () => void;
- /**
- * Called when the upload failed because the user's session has expired, and
- * the Upload component wants to prompt the user to log in again.
- */
onShowSessionExpiredDialog: () => void;
- /**
- * If true, the upload is being initiated from the hidden albums section.
- *
- * When set, the collection selector will only show hidden albums, and any
- * new albums created will be hidden albums.
- */
isInHiddenSection?: boolean;
}
@@ -160,9 +121,7 @@ type UploadType = "files" | "folders" | "zips";
interface UploadFilesOptions {
persistPendingUploads?: boolean;
postUploadTargetCollection?: Collection;
- /** Whether Takeout-favorited uploads should be added to Favorites. */
importTakeoutFavorites?: boolean;
- /** Whether media originating from Google Photos partner sharing is uploaded. */
includePartnerSharedFiles?: boolean;
}
@@ -205,9 +164,6 @@ type UploadConfirmationState =
const containsJSONFiles = (uploadItemAndPaths: UploadItemAndPath[]) =>
uploadItemAndPaths.some(([, path]) => lowercaseExtension(path) == "json");
-/**
- * Top level component that houses the infrastructure for handling uploads.
- */
export const Upload: React.FC<UploadProps> = ({
user,
isFirstUpload,
@@ -258,71 +214,19 @@ export const Upload: React.FC<UploadProps> = ({
} = useModalVisibility();
const didSubmitNewAlbumName = useRef(false);
- /**
- * {@link File}s that the user drag-dropped or selected for uploads (web).
- *
- * This is the only type of selection that is possible when we're running in
- * the browser.
- */
const [webFiles, setWebFiles] = useState<File[]>([]);
- /**
- * {@link File}s that the user drag-dropped or selected for uploads,
- * augmented with their paths (desktop).
- *
- * These siblings of {@link webFiles} come into play when we are running in
- * the context of our desktop app.
- */
const [desktopFiles, setDesktopFiles] = useState<FileAndPath[]>([]);
- /**
- * Paths of file to upload that we've received over the IPC bridge from the
- * code running in the Node.js layer of our desktop app.
- *
- * Unlike {@link filesWithPaths} which are still user initiated,
- * {@link desktopFilePaths} can be set via programmatic action. For example,
- * if the user has setup a folder watch, and a new file is added on their
- * local file system in one of the watched folders, then the relevant path
- * of the new file would get added to {@link desktopFilePaths}.
- */
const [desktopFilePaths, setDesktopFilePaths] = useState<string[]>([]);
- /**
- * (zip file path, entry within zip file) tuples for zip files that the user
- * is trying to upload.
- *
- * These are only set when we are running in the context of our desktop app.
- * They may be set either on a user action (when the user selects or
- * drag-drops zip files) or programmatically (when the app is trying to
- * resume pending uploads from a previous session).
- */
const [desktopZipItems, setDesktopZipItems] = useState<ZipItem[]>([]);
const [preUploadSkippedFiles, setPreUploadSkippedFiles] = useState<
PreUploadSkippedFile[]
>([]);
- /**
- * Consolidated and cleaned list obtained from {@link webFiles},
- * {@link desktopFiles}, {@link desktopFilePaths} and
- * {@link desktopZipItems}.
- *
- * Augment each {@link UploadItem} with its "path" (relative path or name in
- * the case of {@link webFiles}, absolute path in the case of
- * {@link desktopFiles}, {@link desktopFilePaths}, and the path within the
- * zip file for {@link desktopZipItems}).
- *
- * See the documentation of {@link UploadItem} for more details.
- */
const uploadItemsAndPaths = useRef<UploadItemAndPath[]>([]);
- /**
- * If true, then the next upload we'll be processing was initiated by our
- * desktop app.
- */
const isPendingDesktopUpload = useRef(false);
- /**
- * If set, this will be the name of the collection that our desktop app
- * wishes for us to upload into.
- */
const pendingDesktopUploadCollectionName = useRef<string | undefined>(
undefined,
);
@@ -333,47 +237,22 @@ export const Upload: React.FC<UploadProps> = ({
>
>({});
- /**
- * This is set to thue user's choice when the user chooses one of the
- * predefined type to upload from the upload type selector dialog
- */
const selectedUploadType = useRef<UploadType | undefined>(undefined);
const currentUploadPromise = useRef<Promise<void> | undefined>(undefined);
const uploadRunning = useRef(false);
const isDragAndDrop = useRef(false);
- /**
- * Used to remember a deferred "real destination" collectionf or the current upload flow.
- * So this ref remembers the original shared album target across failed uploads.
- */
+ // Preserve the real shared-album destination across retries.
const retrySharedAlbumUploadTarget = useRef<Collection | undefined>(
undefined,
);
- /** The confirmed favorites choice for retrying the current batch. */
const retryImportTakeoutFavorites = useRef(true);
- /** The confirmed partner-sharing choice for retrying the current batch. */
const retryIncludePartnerSharedFiles = useRef(true);
- /**
- * `true` if we've activated one hidden {@link Inputs} that allow the user
- * to select items, and haven't heard back from the browser as to the
- * selection (or cancellation).
- *
- * [Note: Showing an activity indicator during upload item selection]
- *
- * When selecting a large number of items (100K+), the browser can take
- * significant time (10s+) before it hands back control to us. The
- * {@link isInputPending} state tracks this intermediate state, and we use
- * it to show an activity indicator to let that the user know that their
- * selection is still being processed.
- */
+ // Browser selection can take over ten seconds for 100k files.
const [isInputPending, setIsInputPending] = useState(false);
- /**
- * Files that were selected by the user in the last activation of one of the
- * hidden {@link Inputs}.
- */
const [selectedInputFiles, setSelectedInputFiles] = useState<File[]>([]);
const handleInputSelect = useCallback((files: File[]) => {
@@ -490,12 +369,8 @@ export const Upload: React.FC<UploadProps> = ({
}
}, []);
- // Handle selected files when user selects files for upload through the open
- // file / open folder selection dialog, or drag-and-drops them.
useEffect(() => {
if (watchFolderView) {
- // if watch folder dialog is open don't catch the dropped file
- // as they are folder being dropped for watching
return;
}
@@ -529,35 +404,12 @@ export const Upload: React.FC<UploadProps> = ({
}
}, [selectedInputFiles, dragAndDropFiles]);
- // Trigger an upload when any of the dependencies change.
useEffect(() => {
- // About the paths:
- //
- // - These are not necessarily the full paths. In particular, when
- // running on the browser they'll be the relative paths (at best) or
- // just the file-name otherwise.
- //
- // - All the paths use POSIX separators. See inline comments.
- //
- // - For zips we concatenate the path of the zip to the path within the
- // zip for the purpose of computing the nesting.
+ // ZIP paths are synthetic and used only for folder grouping.
const allItemAndPaths = [
- // Relative path (using POSIX separators) or the file's name.
webFiles.map((f) => [f, pathLikeForWebFile(f)]),
- // The paths we get from the desktop app all eventually come either
- // from electron.selectDirectory or electron.pathForFile, both of
- // which return POSIX paths.
desktopFiles.map((fp) => [fp, fp.path]),
desktopFilePaths.map((p) => [p, p]),
- // Concatenate the path of the item within the zip to path of the
- // zip. This won't affect the upload: this path is only used for
- // computation of the "parent" folder, and this concatenation best
- // reflects the nesting.
- //
- // Re POSIXness: The first path, that of the zip file itself, is
- // POSIX like the other paths we get over the IPC boundary. And the
- // second path, ze[1], the entry name, uses POSIX separators because
- // that is what the ZIP format uses.
desktopZipItems.map((ze) => [ze, joinPath(dirname(ze[0]), ze[1])]),
].flat() as UploadItemAndPath[];
@@ -611,7 +463,7 @@ export const Upload: React.FC<UploadProps> = ({
props.closeUploadTypeSelector();
props.setLoading(true);
- // Starting a new upload discards any stale pending confirmation.
+ // Do not reuse a confirmation from an earlier selection.
setUploadConfirmation(undefined);
setWebFiles([]);
setDesktopFiles([]);
@@ -646,9 +498,7 @@ export const Upload: React.FC<UploadProps> = ({
pendingDesktopUploadConfirmationOptions.current;
pendingDesktopUploadConfirmationOptions.current = {};
if (pendingDesktopUploadCollectionName.current) {
- // Include hidden collections so watch folder syncs add
- // files to existing hidden albums instead of creating new
- // visible ones
+ // Watch folders must match hidden albums instead of duplicating them.
uploadFilesToNewCollections("root", {
collectionName:
pendingDesktopUploadCollectionName.current,
@@ -721,18 +571,6 @@ export const Upload: React.FC<UploadProps> = ({
uploadManager.showUploadProgressDialog();
};
- /**
- *
- * @param batchResult
- * @param targetCollection
- *
- * This function actually receives the batchResult which is the post-upload
- * object and the target collection of upload.
- *
- * the {@link successfulFilesFromUploadBatchResult} take the batchResult
- * and then returns an array of files which is of the type {@link EnteFile}
- * this file is then added to the corresponding shared album.
- */
const handlePostUploadBatchResult = async (
batchResult: UploadBatchResult,
targetCollection: Collection | undefined,
@@ -759,15 +597,6 @@ export const Upload: React.FC<UploadProps> = ({
}
};
- /**
- *
- * @param batchResult
- * @param postUploadTargetCollection
- * @returns
- *
- * Adds successfully uploaded Takeout-favorited files to Favorites, skipping
- * files whose effective target collection is hidden.
- */
const handleTakeoutFavoritesPostUpload = async (
batchResult: UploadBatchResult,
postUploadTargetCollection: Collection | undefined,
@@ -775,7 +604,6 @@ export const Upload: React.FC<UploadProps> = ({
) => {
if (!importTakeoutFavorites) return;
- // Checking if any of the uploaded items have their takeoutFavorited as true.
if (
!batchResult.itemResults.some(
({ takeoutFavorited }) => takeoutFavorited,
@@ -784,33 +612,20 @@ export const Upload: React.FC<UploadProps> = ({
return;
}
- // Get the list of IDs of hidden collections.
const hiddenCollectionIDs = new Set(
(await savedHiddenCollections()).map(({ id }) => id),
);
- // In some cases, such as when the upload is happening to a non-owned album,
- // files are first added to the user's own album and then, after upload,
- // linked to the shared album.
- //
- // For such cases, check whether the real intended upload location is a
- // hidden album and add it to the set.
if (
postUploadTargetCollection &&
isHiddenCollection(postUploadTargetCollection)
) {
+ // The temporary upload album is not the effective destination.
hiddenCollectionIDs.add(postUploadTargetCollection.id);
}
- /**
- * Treating the requestCollectionID as a hidden album because the upload was
- * initated from the hidden-albums UI.
- *
- * savedHiddenCollections will already include hidden collections, but it is not
- * guaranteed to include every hidden album. So this is also a guard at the UI
- * level.
- */
if (props.isInHiddenSection) {
+ // The pull may not include every newly created hidden album yet.
for (const { requestedCollectionID } of batchResult.itemResults) {
hiddenCollectionIDs.add(requestedCollectionID);
}
@@ -1051,11 +866,7 @@ export const Upload: React.FC<UploadProps> = ({
const collections: Collection[] = [];
try {
await onRemoteFilesPull();
- // When uploading to hidden section (createHidden), only search
- // hidden collections. When syncing from watch folders
- // (includeHiddenCollections), search all collections so files go
- // to existing albums regardless of visibility. Otherwise, search
- // only normal (visible) collections.
+ // Hidden uploads search hidden albums only. Watch folders search all.
const existingCollections = createHidden
? await savedHiddenCollections()
: includeHiddenCollections
@@ -1238,8 +1049,7 @@ export const Upload: React.FC<UploadProps> = ({
if (watcher.isUploadRunning()) {
await watcher.allFileUploadsDone(uploadItemsWithCollection);
} else if (watcher.isSyncPaused()) {
- // Resume folder watch after the user upload that
- // interrupted it is done.
+ // Resume the watch upload displaced by this user upload.
watcher.resumePausedSync();
}
}
@@ -1342,8 +1152,7 @@ export const Upload: React.FC<UploadProps> = ({
const handleUploadTypeSelect = (type: UploadType) => {
selectedUploadType.current = type;
- // Opening native file/folder pickers can blur the app window on
- // desktop; suppress blur-triggered app lock for this trusted flow.
+ // Native pickers blur the window; this trusted flow must not lock it.
if (electron) {
suppressAutoLockOnBlurForTrustedPrompt();
}
@@ -1456,12 +1265,6 @@ interface InputsProps {
getZipFileSelectorInputProps: GetInputProps;
}
-/**
- * Create a bunch of HTML inputs elements, one each for the given props.
- *
- * These hidden input element serve as the way for us to show various file /
- * folder Selector dialogs and handle drag and drop inputs.
- */
const Inputs: React.FC<InputsProps> = ({
getFileSelectorInputProps,
getFolderSelectorInputProps,
@@ -1495,9 +1298,7 @@ const desktopFilesAndZipItems = async (electron: Electron, files: File[]) => {
result.preUploadSkippedFiles,
);
} catch (e) {
- // IPC failure (desktop returns malformed zips as part of
- // the response, so reaching this catch means something
- // more fundamental went wrong).
+ // Malformed ZIPs return as data; this catch means IPC failed.
log.error("Failed to list zip items", e);
preUploadSkippedFiles.push({
name: file.name,
@@ -1512,38 +1313,13 @@ const desktopFilesAndZipItems = async (electron: Electron, files: File[]) => {
return { fileAndPaths, zipItems, preUploadSkippedFiles };
};
-/**
- * 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 the react-dropzone library that we use
- * will internally convert `webkitRelativePath` to `path`, but otherwise it
- * behaves same as case 2.
- * https://github.com/react-dropzone/file-selector/blob/master/src/file.ts#L1214
- */
const pathLikeForWebFile = (file: File): string =>
firstNonEmpty([
- // We need to check first, since path is not a property of
- // the standard File objects.
"path" in file && typeof file.path == "string" ? file.path : undefined,
file.webkitRelativePath,
file.name,
])!;
-/**
- * This is used to prompt the user the make upload strategy choice.
- *
- * This is derived from the items that the user selected.
- */
interface ImportSuggestion {
rootFolderName: string;
hasNestedFolders: boolean;
@@ -1566,6 +1342,7 @@ const deriveImportSuggestionFromPaths = (
return { ...defaultImportSuggestion, rootFolderPath: "" };
}
+ // All paths here use POSIX separators.
const separatorCounts = new Map(
paths.map((s) => [s, s.match(/\//g)?.length ?? 0]),
);
@@ -1603,16 +1380,6 @@ const deriveImportSuggestionFromPaths = (
};
};
-/**
- *
- * @param uploadType
- * @param uploadItemAndPaths
- * @returns
- *
- * rootFolderName: The name of root folder, if there exist a metadata.json in the
- * same directory which has a valid title we will be using that else will
- * fallback to the directory foldername.
- */
const deriveImportSuggestion = async (
uploadType: UploadType | undefined,
uploadItemAndPaths: UploadItemAndPath[],
@@ -1644,21 +1411,16 @@ const matchExistingOrCreateAlbum = async (
createHidden?: boolean,
) => {
for (const collection of existingCollections) {
- // When creating a hidden album, only match hidden collections.
- // This prevents hidden uploads from going to visible albums.
+ // Hidden uploads must not match a visible album with the same name.
if (createHidden && !isHiddenCollection(collection)) continue;
if (
- // Name matches
collection.name == albumName &&
- // Valid types
(collection.type == "album" ||
collection.type == "folder" ||
collection.type == "uncategorized") &&
- // Not a quicklink
collection.magicMetadata?.data.subType !=
CollectionSubType.quicklink &&
- // Owned by user
collection.owner.id == user.id
) {
log.info(
@@ -1684,15 +1446,6 @@ const setPendingUploads = async (
includePartnerSharedFiles: boolean,
) => {
let collectionName: string | undefined;
- /* collection being one suggest one of two things
- 1. Either the user has upload to a single existing collection
- 2. Created a new single collection to upload to
- may have had multiple folder, but chose to upload
- to one album
- hence saving the collection name when upload collection count is 1
- helps the info of user choosing this options
- and on next upload we can directly start uploading to this collection
- */
if (collections.length == 1) {
collectionName = collections[0]!.name;
}
@@ -1722,30 +1475,11 @@ const setPendingUploads = async (
};
type UploadTypeSelectorProps = ModalVisibilityProps & {
- /**
- * The particular context / scenario in which this upload is occurring.
- */
intent: UploadTypeSelectorIntent;
- /**
- * If we're waiting on the user to select items using a previously activated
- * file input, then this will be set to the type of that input.
- */
pendingUploadType: UploadType | undefined;
- /**
- * Called when the user selects one of the options.
- */
onSelect: (type: UploadType) => void;
};
-/**
- * Request the user to specify which type of file / folder / zip it is that they
- * wish to upload.
- *
- * This selector (and the "Upload" button) is functionally redundant, the user
- * can just drag and drop any of these into the app to directly initiate the
- * upload. But having an explicit easy to reach button is also necessary for new
- * users, or for cases where drag-and-drop might not be appropriate.
- */
const UploadTypeSelector: React.FC<UploadTypeSelectorProps> = ({
open,
onClose,
@@ -1754,8 +1488,7 @@ const UploadTypeSelector: React.FC<UploadTypeSelectorProps> = ({
onSelect,
}) => {
const handleClose: DialogProps["onClose"] = () => {
- // Disable backdrop clicks and esc keypresses if a selection is pending
- // processing so that the user doesn't inadvertently close the dialog.
+ // The browser may still be processing the selection after the picker closes.
if (pendingUploadType) return;
onClose();
};
@@ -1812,15 +1545,7 @@ const UploadOptions: React.FC<UploadOptionsProps> = ({
onSelect,
onClose,
}) => {
- // [Note: Dialog state remains preserved on reopening]
- //
- // Keep dialog content specific state here, in a separate component, so that
- // this state is not tied to the lifetime of the dialog.
- //
- // If we don't do this, then a MUI dialog retains whatever it was doing when
- // it was last closed. Sometimes that is desirable, but sometimes not, and
- // in the latter cases moving the instance specific state to a child works.
-
+ // Keep dialog state in this child so it resets when the dialog closes.
const [showTakeoutOptions, setShowTakeoutOptions] = useState(false);
const handleTakeoutClose = () => setShowTakeoutOptions(false);
diff --git a/web/apps/photos/src/components/gallery/reducer.ts b/web/apps/photos/src/components/gallery/reducer.ts
index 82a47a638c..15c1d90cfb 100644
--- a/web/apps/photos/src/components/gallery/reducer.ts
+++ b/web/apps/photos/src/components/gallery/reducer.ts
@@ -43,434 +43,82 @@ import { includes } from "ente-utils/type-guards";
import { t } from "i18next";
import React, { useReducer } from "react";
-/**
- * Specifies what the bar at the top of the gallery is displaying currently.
- *
- * TODO: Deprecated(?). Use GalleryView instead. Deprecated if it can be used in
- * all cases where the bar mode was in use.
- */
+// TODO: Deprecated(?). Use GalleryView instead. Deprecated if it can be used in
+// all cases where the bar mode was in use.
export type GalleryBarMode =
| "albums"
| "hidden-albums"
| "archive-albums"
| "people";
-/**
- * Specifies what the gallery is currently displaying.
- *
- * This can be overridden by the display of search results.
- */
export type GalleryView =
| {
- /**
- * We're in the Albums, Hidden albums, or Archive section.
- */
type: "albums" | "hidden-albums" | "archive-albums";
activeCollectionSummaryID: number;
- /**
- * If the active collection ID is for a collection and not a
- * pseudo-collection, this property will be set to the corresponding
- * {@link Collection}.
- *
- * It is guaranteed that this will be one of the {@link collections}.
- */
activeCollection: Collection | undefined;
- /**
- * The currently active collection summary.
- */
activeCollectionSummary: CollectionSummary;
}
| {
- /**
- * We're in the "People" section.
- */
type: "people";
- /**
- * The list of people to show in the gallery bar.
- *
- * Note that this can be different from the underlying list of
- * visiblePeople in the {@link peopleState}, and can temporarily
- * include a person from outside that list.
- */
visiblePeople: Person[];
- /**
- * The full list of people, with temporary hide/delete state applied.
- */
people: Person[];
- /**
- * The currently selected person in the gallery bar, if any.
- *
- * It is guaranteed that when it is set, {@link activePerson} will be
- * one of the objects from among {@link people}.
- */
activePerson: Person | undefined;
};
-/**
- * Derived UI state backing the gallery.
- *
- * This might be different from the actual different from the actual underlying
- * state since there might be unsynced data (hidden or deleted that have not yet
- * been synced with remote) that should be temporarily taken into account for
- * the UI state until the operation completes.
- */
export interface GalleryState {
- /*--< Mostly static state >--*/
-
- /**
- * The logged in {@link LocalUser}.
- *
- * This is expected to be undefined only for a brief duration until the code
- * for the initial "mount" runs (If we're not logged in, then the gallery
- * will redirect the user to an appropriate authentication page).
- */
user: LocalUser | undefined;
- /**
- * Family plan related information for the logged in {@link LocalUser}.
- */
familyData: FamilyData | undefined;
- /*--< Primary state: Files, collections, people >--*/
-
- /**
- * The user's collections.
- */
collections: Collection[];
- /**
- * The user's files, without any unsynced modifications applied to them.
- *
- * The list is sorted so that newer files are first.
- *
- * This property is expected to be of use only internal to the reducer;
- * external code should only needs {@link files} instead.
- */
lastSyncedCollectionFiles: EnteFile[];
- /**
- * The items in the user's trash.
- *
- * The items are sorted in ascending order of their time to deletion. For
- * more details about the sorting order, see {@link sortTrashItems}.
- */
trashItems: TrashItem[];
- /**
- * Latest snapshot of people related state, as reported by
- * {@link usePeopleStateSnapshot}.
- */
peopleState: PeopleState | undefined;
- /*--< Derived state >--*/
-
- /**
- * The user's "collection files", with any unsynced modifications also
- * applied to them.
- *
- * "Collection files" means that there might be multiple entries for the
- * same file ID, one for each collection the file belongs to. For more
- * details, see [Note: Collection file].
- *
- * The list is sorted so that newer files are first.
- *
- * See {@link lastSyncedFiles} for the same list, but without unsynced
- * modifications.
- *
- * [Note: Unsynced modifications]
- *
- * Unsynced modifications are those whose effects have already been made on
- * remote (so thus they have been "saved", so to say), but we still haven't
- * yet refreshed our local state to incorporate them. The refresh will
- * happen on the next files pull, until then they remain as in-memory state
- * in the reducer.
- */
+ // Includes local overlays until the next remote pull.
collectionFiles: EnteFile[];
- /**
- * Collection IDs of hidden collections.
- */
hiddenCollectionIDs: Set<number>;
- /**
- * Collection IDs of default hidden collections.
- *
- * The default hidden collection contains files that have been hidden
- * individually. Rarely, but it is a technical possibility, multiple clients
- * might create such "default" hidden collections. So this needs to be a set
- * of IDs, but usually will be only one. In either case, the client shows a
- * "merged" default hidden collection to the user.
- */
+ // Concurrent clients can create more than one default-hidden collection.
defaultHiddenCollectionIDs: Set<number>;
- /**
- * File IDs of hidden files.
- *
- * [Note: Hidden files]
- *
- * Files can be individually hidden, or hidden by virtue of being placed in
- * a hidden album. However unlike archiving (See: [Note: Archived files]),
- * in the case of individually hiding a file, we do not set a file level
- * property but rather move it to the "default hidden collection".
- *
- * So effectively, files can be hidden only by virtue of being present in a
- * hidden collection.
- *
- * If a file is present in any hidden collection, then it is considered
- * hidden. Since this computation requires multiple steps, we precompute the
- * list of such files and keep it this set.
- */
hiddenFileIDs: Set<number>;
- /**
- * Collection IDs of archived collections.
- */
archivedCollectionIDs: Set<number>;
- /**
- * File IDs of the files that the user has archived.
- *
- * Includes the effects of {@link unsyncedVisibilityUpdates}.
- *
- * [Note: Archived files]
- *
- * Files can be individually archived (which is a file level property), or
- * archived by virtue of being placed in an archived album (which is a
- * collection file level property).
- *
- * Archived files are not supposed to be shown in the all section,
- * irrespective of which of those two way they obtain their archive status.
- *
- * In particular, a (collection) file can be both in an archived album and
- * an normal album, so just checking for membership in archived collections
- * is not enough to filter them out from all. Instead, we need to compile a
- * list of file IDs that have the archive status, and then filter the
- * collection files using this list.
- *
- * For fast filtering, this is a set instead of a list.
- */
archivedFileIDs: Set<number>;
- /**
- * File IDs of all the files that the user has marked as a favorite.
- *
- * Includes the effects of {@link unsyncedFavoriteUpdates}.
- *
- * For fast lookup, this is a set instead of a list.
- */
favoriteFileIDs: Set<number>;
- /**
- * A map from collection IDs to their user visible name.
- *
- * It will contain entries for all collections (both normal and hidden).
- */
collectionNameByID: Map<number, string>;
- /**
- * A map from file IDs to the IDs of the normal (non-hidden) collections
- * that they're a part of.
- */
fileNormalCollectionIDs: Map<number, number[]>;
- /**
- * A map from known Ente user IDs to their emails
- *
- * This will not have an entry for the user themselves.
- *
- * This is used to perform a fast lookup of the email of the Ente user that
- * shared a file or collection.
- */
emailByUserID: Map<number, string>;
- /**
- * A list of emails that can be served as suggestions when the user is
- * trying to share a collection with another Ente user.
- *
- * These are derived from the emails of the Ente users with whom the user
- * has already shared collections, plus the emails of their family members.
- */
shareSuggestionEmails: string[];
- /*--< Derived UI state >--*/
-
- /**
- * A map of normal (non-hidden) collections massaged into a form suitable
- * for being directly consumed by the UI, indexed by the collection IDs.
- */
normalCollectionSummaries: Map<number, CollectionSummary>;
- /**
- * A variant of {@link normalCollectionSummaries}, but for hidden
- * collections.
- */
hiddenCollectionSummaries: Map<number, CollectionSummary>;
- /**
- * A variant of {@link normalCollectionSummaries}, but for archived
- * collections and the archive section entry.
- */
archivedCollectionSummaries: Map<number, CollectionSummary>;
- /**
- * The ID of the collection summary that should be shown when the user
- * navigates to the uncategorized section.
- *
- * This will be either the ID of the user's uncategorized collection, if one
- * has already been created, otherwise it will be the predefined
- * {@link PseudoCollectionID.uncategorizedPlaceholder}.
- *
- * See: [Note: Uncategorized placeholder]
- */
uncategorizedCollectionSummaryID: number;
- /*--< In-flight updates >--*/
-
- /**
- * File IDs of the files that have been just been deleted by the user.
- *
- * The delete on remote for these has either completed, or is currently in
- * flight, but the local state has not yet been updated. We stash these
- * changes here temporarily so that the UI can reflect the changes until our
- * local state also gets synced in a bit.
- */
tempDeletedFileIDs: Set<number>;
- /**
- * Variant of {@link tempDeletedFileIDs} for files that have just been
- * hidden.
- */
tempHiddenFileIDs: Set<number>;
- /**
- * File (IDs) for which there is currently an in-flight favorite /
- * unfavorite operation.
- *
- * See also {@link unsyncedFavoriteUpdates}.
- */
pendingFavoriteUpdates: Set<number>;
- /**
- * Local favorite status overlay for updates triggered by an interactive
- * user action. Some entries may still be pending remote mutation, while
- * others may have succeeded remotely but not yet been synced back to our
- * local DB.
- *
- * Each entry is keyed by file ID for owned files, and by hash/type for
- * non-owned shared files. This keeps equivalent shared-file updates
- * last-writer-wins before the next remote pull.
- *
- * The next time a remote pull completes, we clear this map since thereafter
- * just deriving {@link favoriteFileIDs} from our local files would reflect
- * the correct state on remote too.
- */
+ // Shared copies use hash/type keys; owned files use IDs.
unsyncedFavoriteUpdates: Map<
UnsyncedFavoriteUpdateKey,
UnsyncedFavoriteUpdate
>;
- /**
- * File (IDs) for which there is currently an in-flight archive / unarchive
- * operation.
- *
- * See also {@link unsyncedPrivateMagicMetadataUpdates}.
- */
pendingVisibilityUpdates: Set<number>;
- /**
- * Updates to file magic metadata (triggered by some interactive user
- * action) that have already been made to applied to remote, but whose
- * effects on remote have not yet been synced back to our local DB.
- *
- * Each entry from a file ID to the magic metadata that should be used for
- * that file instead of what we get from our local DB.
- *
- * The next time a remote pull completes, we clear this map since thereafter
- * the synced files themselves will reflect the latest private magic
- * metadata.
- */
unsyncedPrivateMagicMetadataUpdates: Map<
number,
MagicMetadata<FilePrivateMagicMetadataData>
>;
- /*--< State that underlies transient UI state >--*/
-
- /**
- * The currently selected collection summary, if any.
- *
- * When present, this is used to derive the
- * {@link activeCollectionSummaryID} property of the {@link view}.
- *
- * UI code should use the {@link view}, this property is meant as the
- * underlying primitive state. In particular, this does not get reset when
- * we switch sections, which allows us to come back to the same active
- * collection (if possible) on switching back.
- */
selectedCollectionSummaryID: number | undefined;
- /**
- * The currently selected person, if any.
- *
- * When present, it is used to derive the {@link activePerson} property of
- * the {@link view}.
- *
- * UI code should use the {@link view}, this property is meant as the
- * underlying primitive state. In particular, this does not get reset when
- * we switch sections, which allows us to come back to the same person (if
- * possible) on switching back.
- */
selectedPersonID: string | undefined;
- /**
- * If present, this person is tacked on the the list of visible people
- * temporarily (until the user switches out from the people view).
- *
- * This is needed to retain a usually non-visible but temporarily selected
- * person in the people bar until the user switches to some other view.
- */
extraVisiblePerson: Person | undefined;
- /**
- * The suggestion selected by the user from the search bar dropdown.
- *
- * This is used to compute the {@link searchResults}.
- */
searchSuggestion: SearchSuggestion | undefined;
- /**
- * List of files that match the selected search option.
- *
- * This will be set only if we are showing search results.
- *
- * The search dropdown shows a list of options ("suggestions") that match
- * the user's search term. If the user selects from one of these options,
- * then we run a search to find all files that match that suggestion, and
- * set this value to the result.
- */
searchResults: EnteFile[] | undefined;
- /**
- * `true` an external effect is currently (asynchronously) updating search
- * results.
- */
isRecomputingSearchResults: boolean;
- /**
- * {@link SearchSuggestion}s that have been enqueued while we were
- * recomputing the current search results.
- *
- * We only need the last element of this array (if any), the rest are
- * discarded when we get around to processing these.
- */
pendingSearchSuggestions: SearchSuggestion[];
- /*--< Transient UI state >--*/
-
- /**
- * The view, and the item within it, that the gallery is currently showing.
- *
- * This can be temporarily overridden when we display search results.
- */
view: GalleryView | undefined;
- /**
- * `true` if we are in "search mode".
- *
- * We will always be in search mode if we are showing search results, but we
- * also may be in search mode earlier on smaller screens, where the search
- * input is only shown on entering search mode. See: [Note: "Search mode"].
- *
- * That is, {@link isInSearchMode} may be true even when
- * {@link searchResults} is undefined.
- *
- * We will be _showing_ search results if both {@link isInSearchMode} is
- * `true` and {@link searchResults} is defined.
- */
isInSearchMode: boolean;
- /**
- * Sort order for search results.
- *
- * - `undefined`: No explicit sort selected, keep original order (preserves
- * CLIP relevance sorting for ML searches)
- * - `true`: Ascending order (oldest first)
- * - `false`: Descending order (newest first)
- */
+ // Undefined preserves relevance order; booleans request time sorting.
searchSortAsc: boolean | undefined;
- /**
- * The files to show, uniqued and sorted appropriately.
- */
filteredFiles: EnteFile[];
}
@@ -569,8 +217,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
const lastSyncedCollectionFiles = sortFiles(action.collectionFiles);
const trashItems = sortTrashItems(action.trashItems);
- // During mount there are no unsynced updates, and we can directly
- // use the provided files.
const collectionFiles = lastSyncedCollectionFiles;
const collections = action.collections;
@@ -666,13 +312,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
}
case "setUserDetails": {
- // While user details have more state that can change, the only
- // changes that affect the reducer's state (so far) are if the
- // user's own email changes, or the list of their family members
- // changes.
- //
- // Both of these affect only the list of share suggestion emails.
-
let user = state.user!;
const { email, familyData } = action.userDetails;
if (email != user.email) {
@@ -730,7 +369,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
hiddenFileIDs,
);
- // Revalidate the active view if needed.
let view = state.view;
let selectedCollectionSummaryID = state.selectedCollectionSummaryID;
if (state.view?.type == "albums") {
@@ -820,7 +458,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
case "uploadFile": {
// TODO: Consider batching this instead of doing it per file
// upload to speed up uploads. Perf test first though.
-
const lastSyncedCollectionFiles = sortFiles([
...state.lastSyncedCollectionFiles,
action.file,
@@ -942,8 +579,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
isFavorite: action.isFavorite,
});
- // Skipping a call to stateByUpdatingFilteredFiles since it
- // currently doesn't depend on favorites.
return {
...state,
favoriteFileIDs: deriveFavoriteFileIDs(
@@ -961,8 +596,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
state.pendingVisibilityUpdates,
);
pendingVisibilityUpdates.add(action.fileID);
- // Not using stateByUpdatingFilteredFiles since it does not depend
- // on pendingVisibilityUpdates.
return { ...state, pendingVisibilityUpdates };
}
@@ -995,11 +628,8 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
}
case "clearUnsyncedState": {
- // Getting the last syncedCollectionFiles
const collectionFiles = state.lastSyncedCollectionFiles;
- // Getting the FavoriteFileIDs from the syncedData
- // without applying any optimistic chagnes.
const syncedFavoriteFileIDs = deriveFavoriteFileIDs(
state.user!,
state.collections,
@@ -1236,7 +866,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
});
case "setSearchResults":
- // Discard stale updates
if (!state.isRecomputingSearchResults) return state;
return stateByUpdatingFilteredFiles({
@@ -1246,7 +875,6 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
});
case "exitSearch": {
- // Only exit search mode if explicitly requested (defaults to true for backward compatibility)
const shouldExitSearchMode = action.shouldExitSearchMode ?? true;
return stateByUpdatingFilteredFiles({
...state,
@@ -1271,20 +899,13 @@ const galleryReducer: React.Reducer<GalleryState, GalleryAction> = (
export const useGalleryReducer = () =>
useReducer(galleryReducer, initialGalleryState);
-/**
- * Compute the effective files that we should use by overlaying the files we
- * read from disk by any temporary unsynced updates.
- */
const deriveCollectionFiles = (
lastSyncedCollectionFiles: GalleryState["lastSyncedCollectionFiles"],
unsyncedPrivateMagicMetadataUpdates: GalleryState["unsyncedPrivateMagicMetadataUpdates"],
) => {
- // Happy fastpath.
if (unsyncedPrivateMagicMetadataUpdates.size == 0)
return lastSyncedCollectionFiles;
- // We have one or more unsynced private magic metadata updates that should
- // be applied to all the collection files with the matching file ID.
return lastSyncedCollectionFiles.map((file) => {
const privateMagicMetadata = unsyncedPrivateMagicMetadataUpdates.get(
file.id,
@@ -1295,10 +916,6 @@ const deriveCollectionFiles = (
});
};
-/**
- * Compute various bits of the state associated with hidden items from their
- * dependencies.
- */
const deriveHiddenInfo = (
collections: GalleryState["collections"],
collectionFiles: GalleryState["collectionFiles"],
@@ -1319,9 +936,6 @@ const deriveHiddenInfo = (
};
};
-/**
- * Compute the list of hidden file IDs from their dependencies.
- */
const deriveHiddenFileIDs = (
collectionFiles: GalleryState["collectionFiles"],
hiddenCollectionIDs: GalleryState["hiddenCollectionIDs"],
@@ -1332,15 +946,9 @@ const deriveHiddenFileIDs = (
.map((f) => f.id),
);
-/**
- * Compute the default hidden collection IDs from their dependencies.
- */
const deriveDefaultHiddenCollectionIDs = (hiddenCollections: Collection[]) =>
findDefaultHiddenCollectionIDs(hiddenCollections);
-/**
- * Compute archived collection IDs from their dependencies.
- */
const deriveArchivedCollectionIDs = (collections: Collection[]) =>
new Set<number>(
collections
@@ -1348,9 +956,6 @@ const deriveArchivedCollectionIDs = (collections: Collection[]) =>
.map((collection) => collection.id),
);
-/**
- * Compute archived file IDs from their dependencies.
- */
const deriveArchivedFileIDs = (
archivedCollectionIDs: GalleryState["archivedCollectionIDs"],
collectionFiles: GalleryState["collectionFiles"],
@@ -1365,9 +970,6 @@ const deriveArchivedFileIDs = (
.map((f) => f.id),
);
-/**
- * Compute favorite file IDs from their dependencies.
- */
const deriveFavoriteFileIDs = (
user: LocalUser,
collections: GalleryState["collections"],
@@ -1377,10 +979,7 @@ const deriveFavoriteFileIDs = (
let favoriteFileIDs = new Set<number>();
let favoriteFileHashAndTypeKeys = new Set<string>();
- // Find the user's Favorites collection and derive both the concrete
- // favorite file IDs and the hash/type keys used to match shared copies.
for (const collection of collections) {
- // See: [Note: User and shared favorites]
if (collection.type == "favorites" && collection.owner.id == user.id) {
const favoriteFiles = collectionFiles.filter(
(file) => file.collectionID == collection.id,
@@ -1395,9 +994,7 @@ const deriveFavoriteFileIDs = (
break;
}
}
- // A shared file has a different ID from the user-owned copy in Favorites.
- // If its hash/type key matches a favorite entry, mark the visible shared
- // file ID as favorite so the UI can show the star in shared albums.
+ // Shared copies have different IDs from their owned favorite.
for (const file of collectionFiles) {
if (file.ownerID == user.id) continue;
@@ -1407,9 +1004,6 @@ const deriveFavoriteFileIDs = (
}
}
- // Apply favorite changes that have succeeded on remote but have not been
- // pulled into local collectionFiles yet. Hash/type updates apply to every
- // matching shared file; ID-based updates apply only to the clicked file.
for (const update of unsyncedFavoriteUpdates.values()) {
const updatedFileIDs = update.fileHashAndTypeKey
? collectionFiles
@@ -1428,24 +1022,6 @@ const deriveFavoriteFileIDs = (
}
return favoriteFileIDs;
};
-/**
- *
- * @param user The currentLoggedIn User
- *
- * @param collectionFiles The collectionsFiles which the user currently has
- * from state.lastSyncedCollectionFiles
- *
- * @param syncedFavoriteFileIDs: The list of FavoriteFileIDs derived from
- * the collectionFiles without any optimistic updations.
- *
- * @param unsyncedFavoriteUpdates The list of FavoriteFileIDs derived from
- * the collectionFiles including any optimistic updates from the
- * state.unsyncedFavoriteUpdates,
- *
- * @returns the preservedUpdates, If there is atleast one affected file
- * where the synced state still disagrees with, we store that file's update in
- * this variable and return it else, it will be an empty map.
- */
const preserveUnreflectedFavoriteUpdates = (
user: LocalUser,
collectionFiles: GalleryState["collectionFiles"],
@@ -1454,12 +1030,7 @@ const preserveUnreflectedFavoriteUpdates = (
) => {
const preservedUpdates: GalleryState["unsyncedFavoriteUpdates"] = new Map();
- /**
- * Iterating through the unsyncedFavoriteUpdates, if the file has
- * fileHashAndTypeKey it's a shared album file, if so then, finding
- * all non-owned/shared file sin the gallery whose hash/type matches
- * this update and storing their IDs to the updatedFileIDs.
- */
+ // Keep an overlay until a pull reports the same state for every copy.
for (const [key, update] of unsyncedFavoriteUpdates.entries()) {
const updatedFileIDs = update.fileHashAndTypeKey
? collectionFiles
@@ -1472,8 +1043,6 @@ const preserveUnreflectedFavoriteUpdates = (
.map((file) => file.id)
: [update.fileID];
- // So, If there at least one affected file where synced state still
- // disagrees with the optimistic update, we preserve the update, else ignore it.
if (
updatedFileIDs.some(
(fileID) =>
@@ -1487,14 +1056,6 @@ const preserveUnreflectedFavoriteUpdates = (
return preservedUpdates;
};
-/**
- * Earlier the UnsyncedFavoriteUpdate was just an fileID
- * because we only had the option to favorite the owner files.
- * Now we can favorite the non-owned files as well.
- *
- * For which we need to do a fileHashAndTypeKey matching
- * therefore this new interface.
- */
interface UnsyncedFavoriteUpdate {
fileID: number;
fileHashAndTypeKey?: string;
@@ -1508,9 +1069,6 @@ const favoriteFileHashAndTypeKey = (file: EnteFile) => {
return hash ? `${hash}:${file.metadata.fileType}` : undefined;
};
-/**
- * Compute file to (non-hidden) collection mapping from its dependencies.
- */
const deriveFileNormalCollectionIDs = (
collectionFiles: GalleryState["collectionFiles"],
hiddenCollectionIDs: GalleryState["hiddenCollectionIDs"],
@@ -1519,10 +1077,6 @@ const deriveFileNormalCollectionIDs = (
collectionFiles.filter((f) => !hiddenCollectionIDs.has(f.collectionID)),
);
-/**
- * Construct a map from file IDs to the list of collections (IDs) to which the
- * file belongs.
- */
const createFileCollectionIDs = (files: EnteFile[]) =>
files.reduce((result, file) => {
const id = file.id;
@@ -1532,9 +1086,6 @@ const createFileCollectionIDs = (files: EnteFile[]) =>
return result;
}, new Map<number, number[]>());
-/**
- * Compute normal (non-hidden) collection summaries from their dependencies.
- */
const deriveNormalCollectionSummaries = (
normalCollections: Collection[],
user: LocalUser,
@@ -1642,9 +1193,6 @@ const deriveArchiveItemsFiles = (
),
);
-/**
- * Compute hidden collection summaries from their dependencies.
- */
const deriveHiddenCollectionSummaries = (
hiddenCollections: Collection[],
user: LocalUser,
@@ -1672,9 +1220,6 @@ const deriveHiddenCollectionSummaries = (
return hiddenCollectionSummaries;
};
-/**
- * Compute archived collection summaries from their dependencies.
- */
const deriveArchivedCollectionSummaries = (
normalCollections: Collection[],
user: LocalUser,
@@ -1701,10 +1246,6 @@ const deriveArchivedCollectionSummaries = (
return archivedCollectionSummaries;
};
-/**
- * Return the ID of the collection summary that should be shown when the user
- * navigates to the uncategorized section.
- */
const deriveUncategorizedCollectionSummaryID = (
normalCollections: Collection[],
userID: number,
@@ -1734,9 +1275,8 @@ const createCollectionSummaries = (
let sortPriority: CollectionSummarySortPriority =
CollectionSummarySortPriority.other;
+ // Ownership comes first so shared favorites remain sharedIncoming.
if (collection.owner.id != user.id) {
- // This case needs to be the first; the rest assume that they're
- // dealing with collections owned by the user.
type = "sharedIncoming";
attributes.add("shared");
attributes.add("sharedIncoming");
@@ -1757,27 +1297,6 @@ const createCollectionSummaries = (
attributes.add("hideFromCollectionBar");
sortPriority = CollectionSummarySortPriority.system;
} else if (collectionType == "favorites") {
- // [Note: User and shared favorites]
- //
- // "favorites" can be both the user's own favorites, or favorites of
- // other users shared with them. However, all of the latter will get
- // typed as "sharedIncoming" in the first case above.
- //
- // So if we get here and the collection summary has type
- // "favorites", it is guaranteed to be the user's own favorites. We
- // mark these with the type "userFavorites", which gives it special
- // treatment like custom icon etc.
- //
- // However, notice that the type of the _collection_ itself is not
- // changed, so whenever we're checking the type of the collection
- // (not of the collection summary) and we specifically want to
- // target the user's own favorites, we also need to check the
- // collection owner's ID is the same as the logged in user's ID.
- //
- // This case needs to be above the other cases since the primary
- // classification of this collection summary is that it is the
- // user's "favorites", everything else is secondary and can be part
- // of the `attributes` computed below.
type = "userFavorites";
name = t("favorites");
sortPriority = CollectionSummarySortPriority.favorites;
@@ -1799,11 +1318,7 @@ const createCollectionSummaries = (
if (collection.publicURLs.length) {
attributes.add("shared");
attributes.add("sharedViaLink");
- // "sharedOnlyViaLink" stays reserved for the case where the only
- // way the collection is shared is via a public link (no sharees),
- // which decides the primary icon. "sharedViaLink" instead tracks
- // the mere presence of a link, so an album that is shared with
- // people and also has a link still shows the link indicator.
+ // This selects the primary icon; sharedViaLink only adds a badge.
if (!collection.sharees.length) {
attributes.add("sharedOnlyViaLink");
}
@@ -1815,7 +1330,6 @@ const createCollectionSummaries = (
attributes.add("pinned");
sortPriority = CollectionSummarySortPriority.pinned;
}
- // Check for sharee pinned (for incoming shared collections)
if (
type == "sharedIncoming" &&
collection.sharedMagicMetadata?.data.order == CollectionOrder.pinned
@@ -1825,11 +1339,6 @@ const createCollectionSummaries = (
}
if (type == "sharedIncoming" && collectionType == "favorites") {
- // See: [Note: User and shared favorites] above.
- //
- // Use the first letter of the email of the user who shared this
- // particular favorite as a prefix to disambiguate this collection
- // from the user's own favorites.
// TODO: Use the person name when avail
const initial = collection.owner.email?.at(0)?.toUpperCase();
if (initial) {
@@ -1841,7 +1350,6 @@ const createCollectionSummaries = (
const collectionFiles = filesByCollection.get(collection.id);
- // Hide empty favorites from collection bar
if (type == "userFavorites" && !collectionFiles?.length) {
attributes.add("hideFromCollectionBar");
}
@@ -1895,18 +1403,12 @@ const findCoverFiles = (
return coverFiles;
};
-/**
- * Compute the {@link GalleryView} from its dependencies when we are switching
- * to (or back to) the "albums" view, or the underlying collections might've
- * changed.
- */
const deriveAlbumsViewAndSelectedID = (
collections: GalleryState["collections"],
hiddenCollectionIDs: GalleryState["hiddenCollectionIDs"],
collectionSummaries: GalleryState["normalCollectionSummaries"],
selectedCollectionSummaryID: GalleryState["selectedCollectionSummaryID"],
) => {
- // Make sure that the last selected ID is still valid by searching for it.
const candidateCollectionSummary = selectedCollectionSummaryID
? collectionSummaries.get(selectedCollectionSummaryID)
: undefined;
@@ -1938,17 +1440,12 @@ const deriveAlbumsViewAndSelectedID = (
};
};
-/**
- * Sibling of {@link deriveAlbumsViewAndSelectedID} for when we're in the hidden
- * albums section.
- */
const deriveHiddenAlbumsViewAndSelectedID = (
collections: GalleryState["collections"],
hiddenCollectionIDs: GalleryState["hiddenCollectionIDs"],
hiddenCollectionSummaries: GalleryState["hiddenCollectionSummaries"],
selectedCollectionSummaryID: GalleryState["selectedCollectionSummaryID"],
) => {
- // Make sure that the last selected ID is still valid by searching for it.
const selectedCollectionSummary = selectedCollectionSummaryID
? hiddenCollectionSummaries.get(selectedCollectionSummaryID)
: undefined;
@@ -1974,16 +1471,11 @@ const deriveHiddenAlbumsViewAndSelectedID = (
};
};
-/**
- * Sibling of {@link deriveAlbumsViewAndSelectedID} for when we're in the
- * archive albums section.
- */
const deriveArchiveAlbumsViewAndSelectedID = (
collections: GalleryState["collections"],
archivedCollectionSummaries: GalleryState["archivedCollectionSummaries"],
selectedCollectionSummaryID: GalleryState["selectedCollectionSummaryID"],
) => {
- // Make sure that the last selected ID is still valid by searching for it.
const selectedCollectionSummary = selectedCollectionSummaryID
? archivedCollectionSummaries.get(selectedCollectionSummaryID)
: undefined;
@@ -2009,10 +1501,6 @@ const deriveArchiveAlbumsViewAndSelectedID = (
};
};
-/**
- * Compute the {@link GalleryView} from its dependencies when we are switching
- * to (or back to) the "people" view.
- */
const derivePeopleView = (
peopleState: GalleryState["peopleState"],
tempDeletedFileIDs: GalleryState["tempDeletedFileIDs"],
@@ -2026,9 +1514,6 @@ const derivePeopleView = (
let people = peopleState?.people ?? [];
let visiblePeople = peopleState?.visiblePeople ?? [];
if (tempDeletedFileIDs.size + tempHiddenFileIDs.size > 0) {
- // Prune the in-memory temp updates from the actual state to
- // obtain the UI state. Kept inside an preflight check to so
- // that the common path remains fast.
const filterTemp = (ps: Person[]) =>
ps
.map((p) => ({
@@ -2044,10 +1529,7 @@ const derivePeopleView = (
visiblePeople = filterTemp(visiblePeople);
}
- // We might have an extraVisiblePerson that is now part of the visible ones
- // when the user un-ignores a person. If that's the case (which we can
- // detect by its absence from the list of underlying people, since its ID
- // would've changed), clear it out, otherwise we'll end up with two entries.
+ // Keep a selected small cluster visible until the user leaves this view.
if (extraVisiblePerson) {
if (!people.find((p) => p.id == extraVisiblePerson?.id))
extraVisiblePerson = undefined;
@@ -2057,15 +1539,10 @@ const derivePeopleView = (
ps.find((p) => p.id == selectedPersonID);
let activePerson = findByIDIn(visiblePeople);
if (!activePerson) {
- // This might be one of the normally hidden small clusters.
activePerson = findByIDIn(people);
if (activePerson) {
- // Temporarily add this person's entry to the list of people
- // surfaced in the people view.
extraVisiblePerson = activePerson;
} else {
- // We don't have an "All" pseudo-album in people view, so default to
- // the first person in the list (if any).
activePerson = visiblePeople[0];
}
}
@@ -2082,17 +1559,6 @@ const derivePeopleView = (
return { view, extraVisiblePerson };
};
-/**
- * Return a new state from the given {@link state} by recomputing all properties
- * that depend on collection files, using the provided {@link collectionFiles}.
- *
- * Usually, we update state by manually dependency tracking on a fine grained
- * basis, but it results in a duplicate code when the files themselves change,
- * since they effect many things.
- *
- * So this is a convenience function for updating everything that needs to
- * change when the collections files themselves change.
- */
const stateForUpdatedCollectionFiles = (
state: GalleryState,
collectionFiles: GalleryState["collectionFiles"],
@@ -2154,27 +1620,9 @@ const stateForUpdatedCollectionFiles = (
};
};
-/**
- * Return a new state by recomputing the {@link filteredFiles} property
- * depending on which view we are showing
- *
- * Usually, we update state by manually dependency tracking on a fine grained
- * basis, but it is cumbersome (and mistake prone) to do that for the list of
- * filtered files which depend on a many things.
- *
- * So this is a convenience function for recomputing filtered files whenever any
- * bit of the underlying state that could affect the list of files changes.
- */
const stateByUpdatingFilteredFiles = (state: GalleryState) => {
if (state.isInSearchMode) {
const searchFiles = state.searchResults ?? state.filteredFiles;
- /**
- * the suppressSharedFilesSavedByUser is a utlity function added in during the
- * UploadToSharedAlbum feature implementation.
- *
- * This particular function actually filters out any files which are actually
- * owned by someone else for which the currentUser has a copy.
- */
const visibleSearchFiles = suppressSharedFilesSavedByUser(
searchFiles,
state.user?.id,
@@ -2184,8 +1632,6 @@ const stateByUpdatingFilteredFiles = (state: GalleryState) => {
? state.view.activeCollection
: undefined,
);
- // Only apply time-based sorting if user explicitly selected a sort order.
- // When undefined, keep original order (preserves CLIP relevance sorting).
const filteredFiles =
state.searchSortAsc !== undefined
? sortFiles([...visibleSearchFiles], state.searchSortAsc)
@@ -2222,10 +1668,6 @@ const stateByUpdatingFilteredFiles = (state: GalleryState) => {
}
};
-/**
- * Compute the sorted list of files to show when we're in the "albums" or
- * "hidden-albums", or "archive-albums" view and the dependencies change.
- */
const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
trashItems: GalleryState["trashItems"],
collectionFiles: GalleryState["collectionFiles"],
@@ -2243,14 +1685,6 @@ const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
) => {
const activeCollectionSummaryID = view.activeCollectionSummaryID;
- // Trash is dealt with separately.
- //
- // [Note: Files in trash pseudo collection have deleteBy]
- //
- // When showing the trash pseudo collection, each file in the files array is
- // in fact an instance of `EnteTrashFile` - it has an additional (and
- // optional) `deleteBy` property. The types don't reflect this.
-
if (activeCollectionSummaryID == PseudoCollectionID.trash) {
return uniqueFilesByID([
...trashItems.map(({ file, deleteBy }) => ({ ...file, deleteBy })),
@@ -2263,7 +1697,6 @@ const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
const filteredFiles = collectionFiles.filter((file) => {
if (tempDeletedFileIDs.has(file.id)) return false;
- // "Hidden items" shows all individually hidden files.
if (
activeCollectionSummaryID == PseudoCollectionID.hiddenItems &&
defaultHiddenCollectionIDs.has(file.collectionID)
@@ -2271,14 +1704,7 @@ const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
return true;
}
- // Archived files can only be seen in the archive items, or in their
- // respective collection. Hidden files should be excluded in from
- // archive items (but not from their album).
- //
- // Note that a file may both be archived, AND be part of an archived
- // collection. Such files should be shown in both the archive section
- // and in their respective collection. Thus this (archived file) case
- // needs to be before the following (archived collection) case.
+ // A file can be individually archived and belong to an archived album.
if (isArchivedFile(file)) {
return (
(activeCollectionSummaryID == PseudoCollectionID.archiveItems &&
@@ -2288,28 +1714,21 @@ const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
);
}
- // Files in archived collections can only be seen in their respective
- // collection.
if (archivedCollectionIDs.has(file.collectionID)) {
return activeCollectionSummaryID === file.collectionID;
}
if (activeCollectionSummaryID === PseudoCollectionID.all) {
- // Hidden files should not be shown in "All".
if (hiddenFileIDs.has(file.id)) return false;
if (tempHiddenFileIDs.has(file.id)) return false;
- // Archived files (whether individually archived, or part of some
- // archived album) should not be shown in "All".
if (archivedFileIDs.has(file.id)) {
return false;
}
- // Show all remaining (non-hidden, non-archived) files in "All".
return true;
}
- // Show files that belong to the active collection.
return activeCollectionSummaryID == file.collectionID;
});
@@ -2320,14 +1739,6 @@ const deriveAlbumsOrHiddenAlbumsFilteredFiles = (
);
};
-/**
- * Prepare the list of files for being shown in the gallery.
- *
- * This functions uniques the given collection files so that there is only one
- * entry per file ID. Then it sorts them if the active collection prefers them
- * to be sorted oldest first (by default, lists of collection files are sorted
- * newest first, and we assume that {@link files} are already sorted that way).
- */
const sortAndUniqueFilteredFiles = (
files: EnteFile[],
activeCollection: Collection | undefined,
@@ -2345,12 +1756,8 @@ const suppressSharedFilesSavedByUser = (
currentUserID: number | undefined,
activeCollection: Collection | undefined,
) => {
- // If there is no logged-in user, or if we are inside an active album
- // (this suppression is only needed in non-album views), return the
- // files unchanged.
if (!currentUserID || activeCollection) return files;
- // Collect the hash+type keys for files owned by the current user.
const ownedFileKeys = new Set<string>();
for (const file of files) {
if (file.ownerID != currentUserID) continue;
@@ -2362,23 +1769,15 @@ const suppressSharedFilesSavedByUser = (
if (!ownedFileKeys.size) return files;
return files.filter((file) => {
- // Always keep files owned by the current user.
if (file.ownerID == currentUserID) return true;
- // Keep files whose metadata does not yield a hash.
const hash = metadataHash(file.metadata);
if (!hash) return true;
- // Drop a non-owned file if the user already owns a file with the same
- // hash+type key.
return !ownedFileKeys.has(`${hash}:${file.metadata.fileType}`);
});
};
-/**
- * Compute the sorted list of files to show when we're in the "people" view and
- * the dependencies change.
- */
const derivePeopleFilteredFiles = (
collectionFiles: GalleryState["collectionFiles"],
hiddenFileIDs: GalleryState["hiddenFileIDs"],
@@ -2399,14 +1798,6 @@ const derivePeopleFilteredFiles = (
);
};
-/**
- * Trigger a recomputation of search results if needed.
- *
- * This convenience helper is used on updates to some state (collections, files)
- * that is used to derive the base set of files on which the search are
- * performed. It re-enqueues the current search suggestion as pending, which'll
- * trigger a recomputation of the state's {@link searchResults}.
- */
const enqueuePendingSearchSuggestionsIfNeeded = (
searchSuggestion: GalleryState["searchSuggestion"],
pendingSearchSuggestions: GalleryState["pendingSearchSuggestions"],
@@ -2416,10 +1807,6 @@ const enqueuePendingSearchSuggestionsIfNeeded = (
? [...pendingSearchSuggestions, searchSuggestion]
: pendingSearchSuggestions;
-/**
- * Create a map from the user IDs to their emails, with entries for all Ente
- * users who have shared a collection with the user.
- */
const constructUserIDToEmailMap = (
user: LocalUser,
collections: GalleryState["collections"],
@@ -2438,10 +1825,6 @@ const constructUserIDToEmailMap = (
return userIDToEmail;
};
-/**
- * Create a list of emails that are shown as suggestions to the user when they
- * are trying to share albums with specific users.
- */
const createShareSuggestionEmails = (
user: LocalUser,
familyData: FamilyData | undefined,
diff --git a/web/apps/photos/src/pages/gallery.tsx b/web/apps/photos/src/pages/gallery.tsx
index 4b4f3e9557..ea64083dda 100644
--- a/web/apps/photos/src/pages/gallery.tsx
+++ b/web/apps/photos/src/pages/gallery.tsx
@@ -167,19 +167,6 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import type { FileWithPath } from "react-dropzone";
import { Trans } from "react-i18next";
-/**
- * The default view for logged in users.
- *
- * I heard you like ASCII art.
- *
- * Navbar / Search ^
- * --------------------- |
- * Gallery Bar sticky
- * --------------------- ---/---
- * Photo List Header scrollable
- * --------------------- |
- * Photo List v
- */
const Page: React.FC = () => {
const { logout, showMiniDialog, onGenericError } = useBaseContext();
const {
@@ -209,39 +196,23 @@ const Page: React.FC = () => {
);
const [isFileViewerOpen, setIsFileViewerOpen] = useState(false);
- // Pending navigation from feed item click
const [pendingFileNavigation, setPendingFileNavigation] = useState<{
fileIndex: number;
sidebar?: FileViewerInitialSidebar;
commentID?: string;
}>();
- /**
- * Tracks a pending file addition operation.
- *
- * Used to temporarily store the file and optional source collection ID
- * when adding a single file to a collection, allowing the operation
- * to be completed after any necessary user interactions (like selecting
- * a target collection).
- */
const pendingSingleFileAdd = useRef<
{ file: EnteFile; sourceCollectionSummaryID?: number } | undefined
>(undefined);
- /**
- * A queue to serialize calls to {@link remoteFilesPull}.
- */
+ // Pull pipelines mutate the same local DB and reducer state.
const remoteFilesPullQueue = useRef(new PromiseQueue<void>());
- /**
- * A queue to serialize calls to {@link remotePull}.
- */
const remotePullQueue = useRef(new PromiseQueue<void>());
const [uploadTypeSelectorView, setUploadTypeSelectorView] = useState(false);
const [uploadTypeSelectorIntent, setUploadTypeSelectorIntent] =
useState<UploadTypeSelectorIntent>("upload");
- // If the fix creation time dialog is being shown, then the list of files on
- // which it should act.
const [fixCreationTimeFiles, setFixCreationTimeFiles] = useState<
EnteFile[]
>([]);
@@ -257,13 +228,11 @@ const Page: React.FC = () => {
const userDetails = useUserDetailsSnapshot();
const peopleState = usePeopleStateSnapshot();
- // Modal visibility for the context menu "Add Person" action
const {
show: showContextMenuAssignPerson,
props: contextMenuAssignPersonProps,
} = useModalVisibility();
- // Named people available for assignment (used by context menu)
const namedPeople = useMemo(
() =>
(peopleState?.visiblePeople ?? []).filter(
@@ -284,13 +253,6 @@ const Page: React.FC = () => {
SidebarActionID | undefined
>(undefined);
- /**
- * The last time (epoch milliseconds) when we prompted the user for their
- * password when opening the hidden section.
- *
- * This is used to implement a grace window, where we don't reprompt them
- * for their password for the same purpose again and again.
- */
const lastAuthenticationForHiddenTimestamp = useRef<number>(0);
const { show: showSidebar, props: sidebarVisibilityProps } =
@@ -320,7 +282,6 @@ const Page: React.FC = () => {
props: pickCoverPhotoDialogVisibilityProps,
} = useModalVisibility();
- // Progress UI state for single-file add-to-album from the FileViewer
const [addToAlbumProgress, setAddToAlbumProgress] = useState<{
open: boolean;
phase: AddToAlbumPhase;
@@ -361,8 +322,7 @@ const Page: React.FC = () => {
const handleCloseAuthenticateUser = useCallback(() => {
authenticateUserVisibilityProps.onClose();
- // Reject the pending authentication promise so the caller knows
- // authentication was cancelled (e.g., user clicked backdrop).
+ // Reject the suspended caller when the modal is dismissed.
if (onAuthenticateCancelCallback.current) {
onAuthenticateCancelCallback.current();
onAuthenticateCancelCallback.current = undefined;
@@ -370,9 +330,7 @@ const Page: React.FC = () => {
}, [authenticateUserVisibilityProps.onClose]);
const handleAuthenticate = useCallback(() => {
- // Clear the cancel callback first since authentication succeeded.
onAuthenticateCancelCallback.current = undefined;
- // Then resolve the promise.
if (onAuthenticateCallback.current) {
onAuthenticateCallback.current();
onAuthenticateCallback.current = undefined;
@@ -388,7 +346,6 @@ const Page: React.FC = () => {
[],
);
- // Local aliases.
const {
user,
favoriteFileIDs,
@@ -405,7 +362,6 @@ const Page: React.FC = () => {
filteredFiles,
} = state;
- // Derived aliases.
const barMode = state.view?.type ?? "albums";
const activeCollectionID =
state.view?.type == "people"
@@ -436,9 +392,6 @@ const Page: React.FC = () => {
[state.collectionFiles],
);
- /**
- * the below function is used to conditionallay render the setCover option in the dropdown
- */
const isOwnedAlbumEligibleForCover = useMemo(() => {
if (
isInSearchMode ||
@@ -533,43 +486,28 @@ const Page: React.FC = () => {
void (async () => {
if (!haveMasterKeyInSession() || !(await savedAuthToken())) {
- // If we don't have master key or auth token, reauthenticate.
stashRedirect("/gallery");
router.push("/");
return;
}
if (!(await validateKey())) {
- // If we have credentials but they can't be decrypted, reset.
- //
- // This code is never expected to run, it is only kept as a
- // safety valve.
logout();
return;
}
- // We are logged in and everything looks fine. Proceed with page
- // load initialization.
-
- // One time inits.
preloadImage("/images/subscription-card-background");
initSettings();
setupSelectAllKeyBoardShortcutHandler();
- // Show the initial state while the rest of the sequence proceeds.
dispatch({ type: "showAll" });
- // If this is the user's first login on this client, then show them
- // a message informing the that the initial load might take time.
setIsFirstLoad(getAndClearIsFirstLogin());
- // If the user created a new account on this client, show them the
- // plan options.
if (getAndClearJustSignedUp()) {
showPlanSelector();
}
- // Initialize the reducer.
const user = ensureLocalUser();
const masterKey = await masterKeyFromSession();
if (masterKey) {
@@ -593,7 +531,7 @@ const Page: React.FC = () => {
trashItems: await savedTrashItems(),
});
- // Check for pending album join BEFORE fetching data
+ // Join first so the initial pull includes the new album.
let joinedAlbumId: number | null = null;
if (hasPendingAlbumToJoin()) {
@@ -614,10 +552,8 @@ const Page: React.FC = () => {
}
}
- // Fetch data from remote (this will include the newly joined album if any)
await remotePull({ source: "gallery-mount" });
- // Navigate directly to the joined album
if (joinedAlbumId) {
dispatch({
type: "showCollectionSummary",
@@ -625,13 +561,11 @@ const Page: React.FC = () => {
});
}
- // Clear the first load message if needed.
setIsFirstLoad(false);
- // Start the interval that does a periodic pull.
syncIntervalID = setInterval(
() => remotePull({ silent: true, source: "gallery-periodic" }),
- 5 * 60 * 1000 /* 5 minutes */,
+ 5 * 60 * 1000,
);
if (electron) {
@@ -650,7 +584,6 @@ const Page: React.FC = () => {
}, []);
useEffect(() => {
- // Only act on updates after the initial mount has completed.
if (state.user && userDetails) {
dispatch({ type: "setUserDetails", userDetails });
}
@@ -733,7 +666,6 @@ const Page: React.FC = () => {
}, [state.isRecomputingSearchResults, state.pendingSearchSuggestions]);
const selectAll = (e: KeyboardEvent) => {
- // Don't intercept Ctrl/Cmd + a if the user is typing in a text field.
if (
e.target instanceof HTMLInputElement ||
e.target instanceof HTMLTextAreaElement
@@ -741,17 +673,11 @@ const Page: React.FC = () => {
return;
}
- // Prevent the browser's default select all handling (selecting all the
- // text in the gallery).
e.preventDefault();
- // Don't select all if:
if (
- // - We haven't fetched the user yet;
!user ||
- // - There is nothing to select;
!filteredFiles.length ||
- // - Any of the modals are open.
uploadTypeSelectorView ||
openCollectionSelector ||
sidebarVisibilityProps.open ||
@@ -766,7 +692,6 @@ const Page: React.FC = () => {
return;
}
- // Create a selection with everything based on the current context.
const selected = {
ownCount: 0,
count: 0,
@@ -847,12 +772,6 @@ const Page: React.FC = () => {
[showMiniDialog, logout],
);
- // [Note: Visual feedback to acknowledge user actions]
- //
- // In some infrequent cases, we want to acknowledge some user action (e.g.
- // pressing a keyboard shortcut which doesn't have an immediate on-screen
- // impact). In these cases, we tickle the loading bar at the top to
- // acknowledge that their action.
const handleVisualFeedback = useCallback(() => {
showLoadingBar();
setTimeout(hideLoadingBar, 0);
@@ -862,24 +781,7 @@ const Page: React.FC = () => {
setPendingFileNavigation(undefined);
}, []);
- /**
- * Pull latest collections, collection files and trash items from remote.
- *
- * This wraps the vanilla {@link pullFiles} with two adornments:
- *
- * 1. Any local database updates due to the pull are also reflected in state
- * updates to the Gallery's reducer.
- *
- * 2. Parallel calls are serialized so that there is only one invocation of
- * the underlying {@link pullFiles} at a time.
- *
- * [Note: Full remote pull vs files pull]
- *
- * For interactive operations, if we know that our operation will not have
- * other transitive effects beyond collections, collection files and trash,
- * this is a better option as compared to a full remote pull since it
- * involves a lesser number of API requests (and thus, time).
- */
+ // Use this for collection/file/trash-only effects; a full pull costs more.
const remoteFilesPull = useCallback(
() =>
remoteFilesPullQueue.current.add(() =>
@@ -900,26 +802,11 @@ const Page: React.FC = () => {
[],
);
- /**
- * Perform a serialized full remote pull, also updating our component state
- * to match the updates to the local database.
- *
- * See {@link remoteFilesPull} for the general concept. This is a similar
- * wrapper over the full remote pull sequence which also adds pre-flight
- * checks (e.g. to ensure that the user's session has not expired).
- *
- * This method will usually not throw; exceptions during the pull itself are
- * caught. This is so that this promise can be unguardedly awaited without
- * failing the main operations it forms the tail end of: the remote changes
- * would've already been successfully applied, and possibly transient pull
- * failures should get resolved on the next retry.
- */
const remotePull = useCallback(
async (opts?: RemotePullOpts) =>
remotePullQueue.current.add(async () => {
const { silent, source } = opts ?? {};
- // Pre-flight checks.
if (!navigator.onLine) return;
if (await isSessionInvalid()) {
showSessionExpiredDialog();
@@ -931,13 +818,13 @@ const Page: React.FC = () => {
return;
}
- // The pull itself.
try {
if (!silent) showLoadingBar();
await prePullFiles();
await remoteFilesPull();
await postPullFiles(source);
} catch (e) {
+ // A later pull retries transient failures after remote mutations.
log.error("Remote pull failed", e);
} finally {
dispatch({ type: "clearUnsyncedState" });
@@ -1005,7 +892,6 @@ const Page: React.FC = () => {
(op: CollectionOp) => (selectedCollection: Collection) => {
const selectedFiles = getSelectedFiles(selected, filteredFiles);
const userFiles = selectedFiles.filter(
- // If a selection is happening, there must be a user.
(f) => f.ownerID == user!.id,
);
const sourceCollectionID = selected.collectionID;
@@ -1060,11 +946,6 @@ const Page: React.FC = () => {
void (async () => {
try {
- /**
- * The add/copy path can process non-owned files when a
- * shared album requires copying them through the current
- * user's library.
- */
const filesToProcess =
op == "add" ? selectedFiles : userFiles;
await performSelectedCollectionOp(
@@ -1103,7 +984,6 @@ const Page: React.FC = () => {
silent: true,
source: "single-file-add-new-album",
});
- // Show custom toast with album name and navigation
setAddToAlbumProgress({
open: true,
phase: "done",
@@ -1116,8 +996,6 @@ const Page: React.FC = () => {
}
setPostCreateAlbumOp((postCreateAlbumOp) => {
- // The function returned by createHandleCollectionOp does its
- // own progress and error reporting, defer to that.
createOnSelectForCollectionOp(postCreateAlbumOp!)(
collection,
);
@@ -1137,12 +1015,7 @@ const Page: React.FC = () => {
const filesToProcess: EnteFile[] = [];
let skippedUnsupportedSharedFile = false;
- /**
- * We currently can only process files which either the currentUser is the owner
- * or the file has a valid metadataHash with it, so checking if we have
- * any unspported files and if so then setting the variable flag as true
- * for showing the modal later on.
- */
+ // Shared copies need a metadata hash to find their owned equivalent.
for (const file of selectedFiles) {
if (file.ownerID == user!.id || metadataHash(file.metadata)) {
filesToProcess.push(file);
@@ -1151,16 +1024,10 @@ const Page: React.FC = () => {
}
}
- // if there are no files to process, like if every file
- // we got to process was unsupported then returning the flag and state.
if (!filesToProcess.length) {
return { processed: false, skippedUnsupportedSharedFile };
}
- // if we have files to process then, checking what the op is
- // favorite and then creating a map of the current state before
- // doing anything. So if the API call fails later, the code knows
- // how to restore each file back to its old state.
const isFavorite = op == "favorite";
const previousFavoriteByFileID = new Map(
filesToProcess.map((file) => [
@@ -1169,14 +1036,6 @@ const Page: React.FC = () => {
]),
);
- /**
- * Looping through the filesToProcess to do two things
- * - addPendingFavoriteUpdate: Let the UI know that this file currently have a request in progress.
- * So that the user can't trigger simultaneous updates.
- *
- * - unsycnedFavoriteUpdate: This changes the visible favorite state immediately, for a faster user
- * feedback.
- */
for (const file of filesToProcess) {
dispatch({ type: "addPendingFavoriteUpdate", fileID: file.id });
dispatch({ type: "unsyncedFavoriteUpdate", file, isFavorite });
@@ -1221,7 +1080,6 @@ const Page: React.FC = () => {
filteredFiles,
);
const ownedSelectedFiles = selectedFiles.filter(
- // There'll be a user if files are being selected.
(file) => file.ownerID == user!.id,
);
if (!ownedSelectedFiles.length) return;
@@ -1256,9 +1114,7 @@ const Page: React.FC = () => {
return;
}
- // When hiding use all non-hidden files instead of the filtered
- // files since we want to move all files copies to the hidden
- // collection.
+ // Hide every non-hidden copy, including copies outside this view.
const opFiles =
op == "hide"
? state.collectionFiles.filter(
@@ -1288,7 +1144,6 @@ const Page: React.FC = () => {
op == "download"
? selectedFiles
: selectedFiles.filter(
- // There'll be a user if files are being selected.
(file) => file.ownerID == user!.id,
);
if (ownedSelectedFiles.length > 0) {
@@ -1308,10 +1163,6 @@ const Page: React.FC = () => {
);
}
- // Apart from download, the other operations currently only work
- // on the user's own files.
- //
- // See: [Note: Add and move of non-user files].
if (
op != "download" &&
ownedSelectedFiles.length != selectedFiles.length
@@ -1368,7 +1219,6 @@ const Page: React.FC = () => {
],
);
- // Handler for selecting a person from the context menu assign person dialog
const handleContextMenuSelectPerson = useCallback(
(personID: string) => {
contextMenuAssignPersonProps.onClose();
@@ -1379,7 +1229,6 @@ const Page: React.FC = () => {
const handleEditLocationConfirm = useCallback(
async (location: Location) => {
- // Only update files owned by the user
const userFiles = selectedFilesInView.filter(
(f) => f.ownerID == user!.id,
);
@@ -1425,7 +1274,6 @@ const Page: React.FC = () => {
});
}
} else {
- // Pass shouldExitSearchMode to the reducer (defaults to true for backward compatibility)
const shouldExitSearchMode = options?.shouldExitSearchMode ?? true;
dispatch({ type: "exitSearch", shouldExitSearchMode });
}
@@ -1439,20 +1287,7 @@ const Page: React.FC = () => {
const handleShowCollectionSummaryWithID = useCallback(
(collectionSummaryID: number | undefined) => {
- // Trigger a pull of the latest data from remote when opening the trash.
- //
- // This is needed for a specific scenario:
- //
- // 1. User deletes a collection, selecting the option to delete files.
- // 2. Museum acks, and then client does a trash pull.
- //
- // This trash pull will not contain the files that belonged to the
- // collection that got deleted because the collection deletion is a
- // asynchronous operation.
- //
- // So the user might not see the entry for the just deleted file if they
- // were to go to the trash meanwhile (until the next pull happens). To
- // avoid this, we trigger a trash pull whenever it is opened.
+ // Museum deletes collection contents asynchronously; pull on entry.
if (collectionSummaryID == PseudoCollectionID.trash) {
void remoteFilesPull();
}
@@ -1462,16 +1297,6 @@ const Page: React.FC = () => {
[],
);
- /**
- * Switch to gallery view to show a collection or pseudo-collection.
- *
- * @param collectionSummaryID The ID of the {@link CollectionSummary} to
- * show. If not provided, show the "All" section.
- *
- * @param isHidden If `true`, then any reauthentication as appropriate
- * before switching to the hidden section of the app is performed first
- * before before switching to the relevant collection or pseudo-collection.
- */
const showCollectionSummary = useCallback(
async (
collectionSummaryID: number | undefined,
@@ -1482,14 +1307,12 @@ const Page: React.FC = () => {
if (
isHiddenCollectionSummary &&
barMode != "hidden-albums" &&
- Date.now() - lastAuthAt > 5 * 60 * 1e3 /* 5 minutes */
+ Date.now() - lastAuthAt > 5 * 60 * 1e3
) {
try {
await authenticateUser();
lastAuthenticationForHiddenTimestamp.current = Date.now();
} catch {
- // User cancelled authentication (e.g., clicked backdrop).
- // Don't proceed to show the collection.
return;
}
}
@@ -1551,16 +1374,7 @@ const Page: React.FC = () => {
dispatch({ type: "addPendingVisibilityUpdate", fileID });
try {
await updateFilesVisibility([file], visibility);
- // [Note: Interactive updates to file metadata]
- //
- // 1. Update the remote metadata.
- //
- // 2. Construct a fake a metadata object with the updates
- // reflected in it.
- //
- // 3. The caller (eventually) triggers a remote pull in the
- // background, but meanwhile uses this updated metadata.
- //
+ // Keep the UI ahead of the background pull.
// TODO: Replace with files pull?
dispatch({
type: "unsyncedPrivateMagicMetadataUpdate",
@@ -1688,12 +1502,6 @@ const Page: React.FC = () => {
],
);
- /**
- * Handle a context menu action on a file.
- *
- * This handler is called when the user right-clicks on a file thumbnail
- * and selects an action from the context menu.
- */
const handleContextMenuAction = useCallback(
(
action: FileContextAction,
@@ -1701,8 +1509,6 @@ const Page: React.FC = () => {
meta?: { isEphemeralSingleSelection: boolean },
) => {
const suppressSelectionBar = !!meta?.isEphemeralSingleSelection;
- // The selection should already be set by FileList's handleContextMenu
- // We just need to invoke the appropriate action handler
switch (action) {
case "sendLink":
createFileOpHandler("sendLink", { suppressSelectionBar })();
@@ -1903,28 +1709,12 @@ const Page: React.FC = () => {
[],
);
- /**
- * Handles adding a single file to a collection by opening a collection selector dialog.
- *
- * @param file - The EnteFile to be added to a collection
- * @param sourceCollectionSummaryID - Optional ID of the source collection where the file currently resides
- *
- * @remarks
- * This function stores the pending file operation, displays a collection selector modal,
- * and handles three scenarios:
- * - User selects an existing collection: adds the file and triggers a remote pull
- * - User creates a new collection: sets up post-create operation and shows album name input
- * - User cancels: clears the pending operation
- *
- * The function shows/hides a loading bar during the add operation and handles errors generically.
- */
const handleAddSingleFileToCollection = useCallback(
(file: EnteFile, sourceCollectionSummaryID?: number) => {
pendingSingleFileAdd.current = { file, sourceCollectionSummaryID };
const handleSelect = async (collection: Collection) => {
try {
- // Show add-to-album progress UI for this operation.
setAddToAlbumProgress({ open: true, phase: "processing" });
showLoadingBar();
await performCollectionOp(
@@ -1937,7 +1727,6 @@ const Page: React.FC = () => {
silent: true,
source: "single-file-add-to-album",
});
- // Show custom toast with album name and navigation
setAddToAlbumProgress({
open: true,
phase: "done",
@@ -1946,7 +1735,6 @@ const Page: React.FC = () => {
});
} catch (e) {
onGenericError(e);
- // Do not show the toast on failure; handled by generic error notification
} finally {
pendingSingleFileAdd.current = undefined;
hideLoadingBar();
@@ -1988,9 +1776,7 @@ const Page: React.FC = () => {
!(isContextMenuOpen && selected.count === 1);
if (!user) {
- // Don't render until we dispatch "mount" with the logged in user.
- //
- // Tag: [Note: Gallery children can assume user]
+ // Children rely on user after the mount dispatch.
return <div></div>;
}
@@ -2306,9 +2092,7 @@ const Page: React.FC = () => {
label={t("album_name")}
submitButtonTitle={t("create")}
onClose={() => {
- // If the user dismisses the album name dialog without
- // submitting, clear any pending single-file add so that it
- // doesn't leak into a future album creation.
+ // Do not leak a cancelled add into the next album creation.
pendingSingleFileAdd.current = undefined;
albumNameInputVisibilityProps.onClose();
}}
@@ -2361,9 +2145,6 @@ const OfflineMessage: React.FC = () => (
</Typography>
);
-/**
- * Preload all three variants of a responsive image.
- */
const preloadImage = (imgBasePath: string) => {
const srcset: string[] = [];
for (let i = 1; i <= 3; i++) srcset.push(`${imgBasePath}/${i}x.png ${i}x`);
@@ -2371,13 +2152,7 @@ const preloadImage = (imgBasePath: string) => {
};
type NormalNavbarContentsProps = SearchBarProps & {
- /**
- * Called when the user activates the sidebar icon.
- */
onSidebar: () => void;
- /**
- * Called when the user activates the upload button.
- */
onUpload: () => void;
};
@@ -2451,13 +2226,6 @@ const SectionNavbarContents: React.FC<SectionNavbarContentsProps> = ({
</Stack>
);
-/**
- * When the payments app redirects back to us after a plan purchase or update
- * completes, it sets various query parameters to relay the status of the action
- * back to us.
- *
- * Check if these query parameters exist, and if so, act on them appropriately.
- */
const handleSubscriptionCompletionRedirectIfNeeded = async (
showMiniDialog: (attributes: MiniDialogAttributes) => void,
showLoadingBar: () => void,
diff --git a/web/apps/photos/src/services/dedup.ts b/web/apps/photos/src/services/dedup.ts
index 4ec12e1316..6a76d241b9 100644
--- a/web/apps/photos/src/services/dedup.ts
+++ b/web/apps/photos/src/services/dedup.ts
@@ -12,99 +12,22 @@ import {
import { savedCollectionFiles } from "ente-new/photos/services/photos-fdb";
import { pullFiles } from "./pull";
-/**
- * A group of duplicates as shown in the UI.
- */
export interface DuplicateGroup {
- /**
- * A nanoid for this group.
- *
- * This can be used as the key when rendering the group in a list.
- */
id: string;
- /**
- * Files which our algorithm has determined to be duplicates of each other.
- *
- * These are sorted by the collectionName.
- */
items: {
- /**
- * The underlying file to delete.
- *
- * This is one of the files from amongst collection files that have the
- * same ID, arbitrarily picked to stand in for the entire set of files
- * in the UI. The set of the collections to which these files belong is
- * retained separately in {@link collectionIDs}.
- */
file: EnteFile;
- /**
- * IDs of the collection to which {@link file} and its collection file
- * siblings belong.
- */
collectionIDs: Set<number>;
- /**
- * The name of the collection to which {@link file} belongs.
- *
- * Like {@link file} itself, this is an arbitrary pick. Logically, none
- * of the collections to which the file belongs are given more
- * preference than the other.
- */
collectionName: string;
}[];
- /**
- * The size (in bytes) of each item in the group.
- */
itemSize: number;
- /**
- * The number of files that will be pruned if the user decides to dedup this
- * group.
- */
prunableCount: number;
- /**
- * The size (in bytes) that can be saved if the user decides to dedup this
- * group.
- */
prunableSize: number;
- /**
- * `true` if the user has marked this group for deduping.
- */
isSelected: boolean;
}
-/**
- * Find exact duplicates in the user's library, and return them in groups that
- * can then be deduped keeping only one entry in each group.
- *
- * [Note: Deduplication logic]
- *
- * Detecting duplicates:
- *
- * 1. Identify and divide files into multiple groups based on hash.
- *
- * 2. By default select all group, with option to unselect individual groups or
- * all groups.
- *
- * Pruning duplicates:
- *
- * When user presses the dedup button with some selected groups,
- *
- * 1. Identify and select the file which we don't want to delete (preferring
- * file with caption or edited time).
- *
- * 2. For the remaining files identify the collection owned by the user in which
- * the remaining files are present.
- *
- * 3. Add the file that we don't plan to delete to such collections as a
- * symlink.
- *
- * 4. Delete the remaining files.
- */
export const deduceDuplicates = async () => {
- // Find the user's ID.
const userID = ensureLocalUser().id;
- // Find all non-hidden collections owned by the user, and also use that to
- // keep a map of their names (we'll attach this info to the result later).
const normalCollections = await savedNormalCollections();
const normalOwnedCollections = normalCollections.filter(
({ owner }) => owner.id == userID,
@@ -114,55 +37,37 @@ export const deduceDuplicates = async () => {
);
const collectionNameByID = createCollectionNameByID(normalOwnedCollections);
- // Find all eligible collection files.
const collectionFiles = await savedCollectionFiles();
const filteredCollectionFiles = collectionFiles.filter((f) =>
allowedCollectionIDs.has(f.collectionID),
);
- // Group the filtered collection files by their hashes, keeping only one
- // entry per file ID. Also retain the IDs of all the collections to which a
- // particular file (ID) belongs.
+ // One file ID can appear once per collection; hash it only once.
const collectionIDsByFileID = new Map<number, Set<number>>();
const filesByHash = new Map<string, EnteFile[]>();
for (const file of filteredCollectionFiles) {
- // User cannot delete files that are not owned by the user even if they
- // are in an album owned by the user.
+ // An owned album can contain files the user does not own.
if (file.ownerID != userID) continue;
const hash = metadataHash(file.metadata);
if (!hash) {
- // Some very old files uploaded by ancient versions of Ente might
- // not have hashes. Ignore these.
continue;
}
let collectionIDs = collectionIDsByFileID.get(file.id);
if (!collectionIDs) {
collectionIDsByFileID.set(file.id, (collectionIDs = new Set()));
- // This is the first collection file we're seeing for a particular
- // file ID, so also create an entry in the filesByHash map.
filesByHash.set(hash, [...(filesByHash.get(hash) ?? []), file]);
}
collectionIDs.add(file.collectionID);
}
- // Construct the results from groups that have more than one file with the
- // same hash.
const duplicateGroups: DuplicateGroup[] = [];
for (const duplicates of filesByHash.values()) {
if (duplicates.length < 2) continue;
- // Take the size of any of the items, they should all be the same since
- // the hashes are the same.
- //
- // Note that this is not guaranteed in the case of live photos, since
- // the hash originates from the image and video contents, but the size
- // comes from the size of their combined zip, and different clients
- // might use different zip implementation to arrive at non-exact but
- // similar sizes. The delta should be minor so we can use any of the
- // sizes, this is only meant as a rough UI hint anyway.
+ // Live-photo ZIP sizes can vary by client despite matching content hashes.
let size = 0;
for (const file of duplicates) {
if (file.info?.fileSize) {
@@ -171,10 +76,6 @@ export const deduceDuplicates = async () => {
}
}
- // If none of the files marked as duplicates have a size, ignored this
- // group. This shouldn't really happen in practice, but it can happen in
- // rare cases (group of duplicates uploaded by ancient version of Ente
- // which did not attach the file size during uploads).
if (!size) continue;
const items = duplicates
@@ -183,8 +84,6 @@ export const deduceDuplicates = async () => {
file.collectionID,
);
const collectionIDs = collectionIDsByFileID.get(file.id);
- // Ignore duplicates for which we do not have a collection. This
- // shouldn't really happen though, so retain an assert.
if (!collectionName || !collectionIDs) {
assertionFailed();
return undefined;
@@ -195,8 +94,6 @@ export const deduceDuplicates = async () => {
.filter((item) => !!item);
if (items.length < 2) continue;
- // Within each duplicate group, keep the files sorted by collection name
- // so that it is easier to scan them at glance.
items.sort((a, b) => a.collectionName.localeCompare(b.collectionName));
duplicateGroups.push({
@@ -212,57 +109,28 @@ export const deduceDuplicates = async () => {
return duplicateGroups;
};
-/**
- * Remove duplicate groups that the user has selected from those that we
- * returned in {@link deduceDuplicates}.
- *
- * @param duplicateGroups A list of duplicate groups. This is the same list as
- * would've been returned from a previous call to {@link deduceDuplicates},
- * except (a) their sort order might've changed, and (b) the user may have
- * unselected some of them (i.e. isSelected for such items would be `false`).
- *
- * This function will only process entries for which isSelected is `true`.
- *
- * @param onProgress A function that is called with an estimated progress
- * percentage of the operation (a number between 0 and 100).
- *
- * @returns A set containing the IDs of the duplicate groups that were removed.
- */
export const removeSelectedDuplicateGroups = async (
duplicateGroups: DuplicateGroup[],
onProgress: (progress: number) => void,
) => {
const selectedDuplicateGroups = duplicateGroups.filter((g) => g.isSelected);
- // See: "Pruning duplicates" under [Note: Deduplication logic]. A tl;dr; is
- //
- // 1. For each selected duplicate group, determine the file to retain.
- // 2. Add these to the user owned collections the other files exist in.
- // 3. Delete the other files.
-
- /* collection ID => files */
+ // Symlink the retained file into every affected album before trashing duplicates.
const filesToAdd = new Map<number, EnteFile[]>();
- /* only one entry per fileID */
const filesToTrash: EnteFile[] = [];
for (const duplicateGroup of selectedDuplicateGroups) {
const retainedItem = duplicateGroupItemToRetain(duplicateGroup);
- // For each item, find all the collections to which any of the files
- // (except the file we're retaining) belongs.
let collectionIDs = new Set<number>();
for (const item of duplicateGroup.items) {
- // Skip the item we're retaining.
if (item.file.id == retainedItem.file.id) continue;
collectionIDs = collectionIDs.union(item.collectionIDs);
- // Move the item's file to trash.
filesToTrash.push(item.file);
}
- // Skip the existing collection IDs to which this item already belongs.
collectionIDs = collectionIDs.difference(retainedItem.collectionIDs);
- // Add the file we're retaining to these collections.
for (const collectionID of collectionIDs) {
filesToAdd.set(collectionID, [
...(filesToAdd.get(collectionID) ?? []),
@@ -275,7 +143,6 @@ export const removeSelectedDuplicateGroups = async (
const ntotal = filesToAdd.size + filesToTrash.length ? 1 : 0 + /* sync */ 1;
const tickProgress = () => onProgress((np++ / ntotal) * 100);
- // Process the adds.
const collections = await savedNormalCollections();
const collectionsByID = new Map(collections.map((c) => [c.id, c]));
for (const [collectionID, files] of filesToAdd.entries()) {
@@ -283,25 +150,17 @@ export const removeSelectedDuplicateGroups = async (
tickProgress();
}
- // Process the removes.
if (filesToTrash.length) {
await moveToTrash(filesToTrash);
tickProgress();
}
- // Sync our local state.
await pullFiles();
tickProgress();
return new Set(selectedDuplicateGroups.map((g) => g.id));
};
-/**
- * Find the most eligible item from amongst the duplicates to retain.
- *
- * Give preference to files which have a caption or edited name or edited time,
- * otherwise pick arbitrarily.
- */
const duplicateGroupItemToRetain = (duplicateGroup: DuplicateGroup) => {
const itemsWithCaption: DuplicateGroup["items"] = [];
const itemsWithOtherEdits: DuplicateGroup["items"] = [];
@@ -313,7 +172,6 @@ const duplicateGroupItemToRetain = (duplicateGroup: DuplicateGroup) => {
itemsWithOtherEdits.push(item);
}
- // Duplicate group items should not be empty, so we'll get something always.
return (
itemsWithCaption[0] ??
itemsWithOtherEdits[0] ??
diff --git a/web/apps/photos/src/services/export.ts b/web/apps/photos/src/services/export.ts
index 8a02887802..749ee3400b 100644
--- a/web/apps/photos/src/services/export.ts
+++ b/web/apps/photos/src/services/export.ts
@@ -47,13 +47,8 @@ export const CustomError = {
EXPORT_FOLDER_DOES_NOT_EXIST: "export folder does not exist",
};
-/** Name of the JSON file in which we keep the state of the export. */
const exportRecordFileName = "export_status.json";
-/**
- * Name of the top level directory which we create underneath the selected
- * directory when the user starts an export to the file system.
- */
const exportDirectoryName = "Ente Photos";
export const ExportStage = {
@@ -75,46 +70,22 @@ export interface ExportProgress {
total: number;
}
-/**
- * The export related settings that are persisted to local storage.
- */
export interface ExportSettings {
- /**
- * The parent folder where the "Ente Photos" folder containing the export
- * will be placed.
- */
folder?: string;
- /**
- * If `true`, the app will automatically export new or pending files.
- */
continuousExport?: boolean;
}
-/**
- * Zod schema for the {@link ExportSettings} TypeScript type.
- */
const ExportSettings = z.object({
folder: z.string().nullish().transform(nullToUndefined),
continuousExport: z.boolean().nullish().transform(nullToUndefined),
});
-/**
- * Return the previously saved export settings, if any, present in local storage.
- *
- * Use {@link saveExportSettings} to update the settings in local storage.
- */
export const savedExportSettings = () => {
const jsonString = localStorage.getItem("export");
const json = jsonString ? JSON.parse(jsonString) : undefined;
return json ? ExportSettings.parse(json) : undefined;
};
-/**
- * Update the export settings saved in local storage.
- *
- * This is the setter corresponding to {@link savedExportSettings}.
- * @param exportSettings
- */
export const saveExportSettings = (exportSettings: ExportSettings) => {
localStorage.setItem("export", JSON.stringify(exportSettings));
};
@@ -124,11 +95,6 @@ type CollectionExportNames = Record<number, string>;
type FileExportNames = Record<string, string>;
export interface ExportRecord {
- /**
- * The version of the export record.
- *
- * Current version: 5
- */
version: number;
stage: ExportStage;
lastAttemptTimestamp: number;
@@ -146,14 +112,8 @@ export const NULL_EXPORT_RECORD: ExportRecord = {
};
export interface ExportOpts {
- /**
- * If true, perform an additional on-disk check to determine which files
- * need to be exported.
- *
- * This has performance implications for huge libraries, so we only do this:
- * - For the first export after an app start
- * - If the user explicitly presses the "Resync" button.
- */
+ // Huge export folders are expensive to scan.
+ // Scan only at startup or when the user explicitly resyncs.
resync?: boolean;
}
@@ -283,25 +243,12 @@ class ExportService {
this.continuousExportEventHandler = null;
}
- /**
- * Called when the local database of files changes.
- */
onLocalFilesUpdated() {
if (this.continuousExportEventHandler) {
this.continuousExportEventHandler();
}
}
- /**
- * Return the list of files that have not yet been exported.
- *
- * @param exportRecord The export record containing information about the
- * export, including files which've been exported. If an export record is
- * not specified (e.g. if the user has not exported anything yet and we just
- * wish to show a preview of what will be exported), then the function will
- * return the list of all files that will be exported if an export were to
- * happen.
- */
pendingFiles = async (exportRecord?: ExportRecord): Promise<EnteFile[]> => {
return getUnExportedFiles(
await savedCollectionFiles(),
@@ -656,7 +603,6 @@ class ExportService {
);
const collectionExportName =
collectionIDPathMap.get(collectionID);
- // verify that the all exported files from the collection has been removed
const collectionExportedFiles = getCollectionExportedFiles(
exportRecord,
collectionID,
@@ -676,11 +622,9 @@ class ExportService {
collectionID,
);
try {
- // delete the collection metadata folder
await rmdirIfExists(
getMetadataFolderExportPath(collectionExportPath),
);
- // delete the collection folder
await rmdirIfExists(collectionExportPath);
} catch (e) {
await this.addCollectionExportedRecord(
@@ -1183,17 +1127,11 @@ class ExportService {
);
}
- /**
- * Lazily created, cached instance of the date time formatter that should be
- * used for formatting the dates added to the metadata file.
- */
private metadataDateTimeFormatter() {
if (this.cachedMetadataDateTimeFormatter)
return this.cachedMetadataDateTimeFormatter;
- // AFAIK, Google's format is not documented. It also seems to vary with
- // locale. This is a best attempt at constructing a formatter that
- // mirrors the format used by the timestamps in the takeout JSON.
+ // Takeout's undocumented timestamp format varies by locale.
const formatter = new Intl.DateTimeFormat(i18n.language, {
month: "short",
day: "numeric",
@@ -1248,10 +1186,6 @@ const exportService = new ExportService();
export default exportService;
-/**
- * If there are any in-progress exports, or if continuous exports are enabled,
- * resume them.
- */
export const resumeExportsIfNeeded = async () => {
const exportSettings = exportService.getExportSettings();
if (!(await exportService.exportFolderExists(exportSettings?.folder))) {
@@ -1270,11 +1204,6 @@ export const resumeExportsIfNeeded = async () => {
}
};
-/**
- * Prompt the user to select a directory and create an export directory in it.
- *
- * If the user cancels the selection, return undefined.
- */
export const selectAndPrepareExportDirectory = async (): Promise<
string | undefined
> => {
@@ -1294,19 +1223,12 @@ const migrateExportRecordIfNeeded = async (
exportRecord: Partial<ExportRecord>,
) => {
const version = exportRecord.version;
- // The last migration from versions prior to version 5 of the export record
- // was added in Sep 2023 (commit 1fe4d0443b29e77a91981d5800d2c4231118cb83)
- // and released as part of app version 1.6.41:
- // https://github.com/ente/photos-desktop/releases/tag/v1.6.41.
- //
- // There is no traffic from older versions anymore. Still, as an extra
- // precaution, do not proceed if the migration prior to 5 hasn't run by now.
+ // Pre-v5 records should have migrated by desktop 1.6.41; never export through one.
if (version === 0 || version === 1 || version === 2) {
throw new Error(`Unsupported export record version ${version}`);
}
if (version === 3 || version === 4) {
- // The version number in the empty export record was 3 when it should've
- // been 5. Special case for these by ensuring the record is empty.
+ // Old empty records could still report versions 3 or 4.
if (Object.entries(exportRecord.collectionExportNames ?? {}).length) {
throw new Error(`Unsupported export record version ${version}`);
} else {
@@ -1404,10 +1326,6 @@ const getDeletedExportedCollections = (
return deletedExportedCollections;
};
-/**
- * Return export record IDs of {@link files} for which there is also exists a
- * file on disk.
- */
const readOnDiskFileExportRecordIDs = async (
files: EnteFile[],
collectionIDFolderNameMap: Map<number, string>,
@@ -1420,15 +1338,7 @@ const readOnDiskFileExportRecordIDs = async (
const result = new Set<string>();
if (!(await fs.exists(exportDir))) return result;
- // Both the paths involved are guaranteed to use POSIX separators and thus
- // can directly be compared.
- //
- // - `exportDir` traces its origin to `electron.selectDirectory()`, which
- // returns POSIX paths. Down below we use it as the base directory when
- // constructing paths for the items to export.
- //
- // - `findFiles` is also guaranteed to return POSIX paths.
- //
+ // selectDirectory and findFiles both return POSIX paths.
const ls = new Set(await ensureElectron().fs.findFiles(exportDir));
const fileExportNames = exportRecord.fileExportNames ?? {};
@@ -1449,8 +1359,7 @@ const readOnDiskFileExportRecordIDs = async (
if (ls.has(joinPath(collectionExportPath, exportName))) {
result.add(recordID);
} else {
- // It might be a live photo - these store a JSON string instead of
- // the file's name as the exportName.
+ // Live-photo export names are JSON, not filenames.
try {
const { image, video } = parseLivePhotoExportName(exportName);
if (
@@ -1460,7 +1369,7 @@ const readOnDiskFileExportRecordIDs = async (
result.add(recordID);
}
} catch {
- /* Not an error, the file just might not exist on disk yet */
+ // A missing non-live file reaches here.
}
}
}
@@ -1468,19 +1377,6 @@ const readOnDiskFileExportRecordIDs = async (
return result;
};
-/**
- * Return the list of files from amongst {@link allFiles} that still need to be
- * exported.
- *
- * @param allFiles The list of files to export.
- *
- * @param exportRecord The export record containing bookkeeping for the export.
- *
- * @paramd diskFileRecordIDs (Optional) The export record IDs of files from
- * amongst {@link allFiles} that already exist on disk. If provided (e.g. when
- * doing a resync), we perform an extra check for on-disk existence instead of
- * relying solely on the export record.
- */
const getUnExportedFiles = (
allFiles: EnteFile[],
exportRecord: ExportRecord | undefined,
@@ -1553,7 +1449,7 @@ const getGoogleLikeMetadataFile = (
timestamp: `${creationTime}`,
formatted: dateTimeFormatter.format(creationTime * 1000),
},
- // Deprecated, future versions will not write this field.
+ // Deprecated, but still written for export compatibility.
creationTime: {
timestamp: `${creationTime}`,
formatted: dateTimeFormatter.format(creationTime * 1000),
@@ -1573,8 +1469,6 @@ const getGoogleLikeMetadataFile = (
const getMetadataFolderExportPath = (collectionExportPath: string) =>
joinPath(collectionExportPath, exportMetadataDirectoryName);
-// if filepath is /home/user/Ente/Export/Collection1/1.jpg
-// then metadata path is /home/user/Ente/Export/Collection1/ENTE_METADATA_FOLDER/1.jpg.json
const getFileMetadataExportPath = (
collectionExportPath: string,
fileExportName: string,
@@ -1608,15 +1502,6 @@ const parseLivePhotoExportName = (
const isExportInProgress = (exportStage: ExportStage) =>
exportStage > ExportStage.init && exportStage < ExportStage.finished;
-/**
- * Move {@link fileName} in {@link collectionName} to the special per-collection
- * file system "Trash" folder we created under the export directory.
- *
- * Also move its associated metadata JSON to Trash.
- *
- * @param exportDir The root directory on the user's file system where we are
- * exporting to.
- * */
const moveToFSTrash = async (
exportDir: string,
collectionName: string,
diff --git a/web/apps/photos/src/services/watch.ts b/web/apps/photos/src/services/watch.ts
index adc111d97d..53b9bc69f0 100644
--- a/web/apps/photos/src/services/watch.ts
+++ b/web/apps/photos/src/services/watch.ts
@@ -1,8 +1,3 @@
-/**
- * @file Interface with the Node.js layer of our desktop app to provide the
- * watch folders functionality.
- */
-
import debounce from "debounce";
import { ensureElectron } from "ente-base/electron";
import { basename, dirname, lowercaseExtension } from "ente-base/file-name";
@@ -21,64 +16,22 @@ import { computeAllCollectionFilesFromSaved } from "ente-new/photos/services/fil
import { ensureString } from "ente-utils/ensure";
import { type UploadItemWithCollection, uploadManager } from "./upload-manager";
-/**
- * Watch for file system folders and automatically update the corresponding Ente
- * collections.
- *
- * This class relies on APIs exposed over the Electron IPC layer, and thus only
- * works when we're running inside our desktop app.
- */
class FolderWatcher {
- /** Pending file system events that we need to process. */
private eventQueue: WatchEvent[] = [];
- /** The folder watch whose event we're currently processing */
private activeWatch: FolderWatch | undefined;
- /**
- * If the file system directory corresponding to the (root) folder path of a
- * folder watch is deleted on disk, we note down that in this queue so that
- * we can ignore any file system events that come for it next.
- */
+ // A root deletion can be followed by stale child events.
private deletedFolderPaths: string[] = [];
- /**
- * A set of folder paths that were inaccessible in the last accessibility
- * check. Used to detect when a folder transitions from inaccessible to
- * accessible (e.g., when an external drive is reconnected).
- */
private previouslyInaccessiblePaths = new Set<string>();
- /** `true` if we are using the uploader. */
private uploadRunning = false;
- /** `true` if we are temporarily paused to let a user upload go through. */
private isPaused = false;
- /**
- * A map from file paths to the (fileID, collectionID) of the file that was
- * uploaded (or symlinked) as part of the most recent upload attempt.
- */
private uploadedFileForPath = new Map<string, EnteFile>();
- /**
- * A set of file paths that could not be uploaded in the most recent upload
- * attempt. These are the uploads that failed due to a permanent error that
- * a retry will not fix.
- */
private unUploadableFilePaths = new Set<string>();
- /**
- * A function to call when we want to enqueue a new upload of the given list
- * of file paths to the given Ente collection.
- *
- * This is passed as a param to {@link init}.
- */
private upload:
| ((collectionName: string, filePaths: string[]) => void)
| undefined;
- /**
- * A function to call when we want to trigger a full remote pull. It will
- * initiate the pull but will not await its completion.
- *
- * This is passed as a param to {@link init}.
- */
private onTriggerRemotePull: (() => void) | undefined;
- /** A helper function that debounces invocations of {@link runNextEvent}. */
private debouncedRunNextEvent: () => void;
constructor() {
@@ -87,14 +40,6 @@ class FolderWatcher {
this.debouncedRunNextEvent = debounce(() => this.runNextEvent(), 1000);
}
- /**
- * Initialize the watcher and start processing file system events.
- *
- * This is only called when we're running in the context of our desktop app.
- *
- * The caller provides us with the hooks we can use to actually upload the
- * files, and to pull the latest changes from remote (say after deletion).
- */
init(
upload: (collectionName: string, filePaths: string[]) => void,
onTriggerRemotePull: () => void,
@@ -106,11 +51,6 @@ class FolderWatcher {
this.triggerSyncWithDisk();
}
- /**
- * Initialize the accessibility tracking state by capturing which watches
- * are currently inaccessible. This allows subsequent checkAccessibility
- * calls to detect when a folder transitions from inaccessible to accessible.
- */
private initializeAccessibilityState() {
void this.getWatches().then((watches) => {
for (const watch of watches) {
@@ -126,53 +66,33 @@ class FolderWatcher {
});
}
- /** Return `true` if we are currently using the uploader. */
isUploadRunning() {
return this.uploadRunning;
}
- /** Return `true` if syncing has been temporarily paused. */
isSyncPaused() {
return this.isPaused;
}
- /**
- * Temporarily pause syncing and cancel any running uploads.
- *
- * This frees up the uploader for handling user initiated uploads.
- */
pauseRunningSync() {
+ // User uploads share this uploader with folder watch.
this.isPaused = true;
uploadManager.cancelRunningUpload();
}
- /**
- * Resume from a temporary pause, resyncing from disk.
- *
- * Sibling of {@link pauseRunningSync}.
- */
resumePausedSync() {
this.isPaused = false;
this.triggerSyncWithDisk();
}
- /** Return the list of folders we are watching for changes. */
async getWatches(): Promise<FolderWatch[]> {
return await ensureElectron().watch.get();
}
- /**
- * Check accessibility of all watch folders and trigger sync if any
- * previously inaccessible folder has become accessible.
- *
- * This is meant to be called when the app gains focus, allowing us to
- * detect when an external drive has been reconnected.
- */
async checkAccessibility(): Promise<void> {
try {
const watches = await this.getWatches();
- // Determine which folders are currently inaccessible.
const currentlyInaccessiblePaths = new Set<string>();
for (const watch of watches) {
if (watch.isAccessible === false) {
@@ -180,12 +100,9 @@ class FolderWatcher {
}
}
- // Check if any previously inaccessible folder is now accessible.
const newlyAccessiblePaths: string[] = [];
for (const path of this.previouslyInaccessiblePaths) {
if (!currentlyInaccessiblePaths.has(path)) {
- // This folder was inaccessible before but is no longer in
- // the inaccessible set. Check if the watch still exists.
const watchStillExists = watches.some(
(w) => w.folderPath === path,
);
@@ -195,10 +112,8 @@ class FolderWatcher {
}
}
- // Update our tracking of inaccessible paths for the next check.
this.previouslyInaccessiblePaths = currentlyInaccessiblePaths;
- // Only trigger sync if at least one folder became accessible.
if (newlyAccessiblePaths.length > 0 && !this.isPaused) {
log.info(
`Folder watch: ${newlyAccessiblePaths.length} folder(s) became accessible (${newlyAccessiblePaths.join(", ")}), triggering sync`,
@@ -210,33 +125,16 @@ class FolderWatcher {
}
}
- /**
- * Return true if we are currently syncing files that belong to the given
- * {@link folderPath}.
- */
isSyncingFolder(folderPath: string) {
return this.activeWatch?.folderPath == folderPath;
}
- /**
- * Add a new folder watch for the given root {@link folderPath}
- *
- * @param mapping The {@link CollectionMapping} to use to decide which
- * collection do files belonging to nested directories go to.
- *
- * @returns The updated list of watches.
- */
async addWatch(folderPath: string, mapping: CollectionMapping) {
const watches = await ensureElectron().watch.add(folderPath, mapping);
this.triggerSyncWithDisk();
return watches;
}
- /**
- * Remove the folder watch for the given root {@link folderPath}.
- *
- * @returns The updated list of watches.
- */
async removeWatch(folderPath: string) {
return await ensureElectron().watch.remove(folderPath);
}
@@ -269,11 +167,7 @@ class FolderWatcher {
private registerListeners() {
const watch = ensureElectron().watch;
- // [Note: File renames during folder watch]
- //
- // Renames come as two file system events - an `onAddFile` + an
- // `onRemoveFile` - in an arbitrary order.
-
+ // Renames arrive as add and remove events in either order.
watch.onAddFile((path: string, watch: FolderWatch) => {
this.pushEvent({
action: "upload",
@@ -321,7 +215,6 @@ class FolderWatcher {
(watch) => watch.folderPath == event.folderPath,
);
if (!watch) {
- // Possibly stale
skip(`no folder watch for found for ${event.folderPath}`);
return;
}
@@ -338,9 +231,6 @@ class FolderWatcher {
return;
}
- // Here we pass control to the uploader. When the upload is done,
- // the uploader will notify us by calling allFileUploadsDone.
-
this.activeWatch = watch;
this.uploadRunning = true;
@@ -391,11 +281,6 @@ class FolderWatcher {
}
}
- /**
- * Batch the next run of events with the same action, collection and folder
- * path into a single clubbed event that contains the list of all effected
- * file paths from the individual events.
- */
private dequeueClubbedEvent(): ClubbedWatchEvent | undefined {
const event = this.eventQueue.shift();
if (!event) return undefined;
@@ -413,21 +298,14 @@ class FolderWatcher {
return { ...event, filePaths };
}
- /**
- * Callback invoked by the uploader whenever a item we requested to
- * {@link upload} gets uploaded.
- */
onFileUpload(item: UploadItemWithCollection, uploadResult: UploadResult) {
- // Re the usage of ensureString: For desktop watch, the only possibility
- // for a UploadItem is for it to be a string (the absolute path to a
- // file on disk).
+ // Watch uploads use absolute path strings despite UploadItem's wider type.
switch (uploadResult.type) {
case "alreadyUploaded":
case "addedSymlink":
case "uploaded":
case "uploadedWithStaticThumbnail":
{
- // Done.
if (item.isLivePhoto) {
this.uploadedFileForPath.set(
ensureString(item.livePhotoAssets?.image),
@@ -449,7 +327,6 @@ class FolderWatcher {
case "unsupported":
case "tooLarge":
{
- // Non-retriable error.
if (item.isLivePhoto) {
this.unUploadableFilePaths.add(
ensureString(item.livePhotoAssets?.image),
@@ -467,10 +344,6 @@ class FolderWatcher {
}
}
- /**
- * Callback invoked by the uploader whenever all the files we requested to
- * {@link upload} get uploaded.
- */
async allFileUploadsDone(uploadedItems: UploadAsset[]) {
const electron = ensureElectron();
const watch = this.activeWatch!;
@@ -521,9 +394,6 @@ class FolderWatcher {
};
for (const item of uploadedItems) {
- // Re the usage of ensureString: For desktop watch, the only
- // possibility for a UploadItem is for it to be a string (the
- // absolute path to a file on disk).
if (item.isLivePhoto) {
const imagePath = ensureString(item.livePhotoAssets?.image);
const videoPath = ensureString(item.livePhotoAssets?.video);
@@ -571,8 +441,7 @@ class FolderWatcher {
for (const file of syncedFiles)
syncedFileForID.set(file.uploadedFileID, file);
- // Use all collection files (including hidden) so that files removed
- // from the watch folder are also removed from hidden albums.
+ // Include hidden copies when removing files deleted from disk.
const files = await computeAllCollectionFilesFromSaved();
const filesToTrash = files.filter((file) => {
const correspondingSyncedFile = syncedFileForID.get(file.id);
@@ -591,59 +460,25 @@ class FolderWatcher {
}
}
-/** The singleton instance of {@link FolderWatcher}. */
const watcher = new FolderWatcher();
export default watcher;
-/**
- * A file system watch event encapsulates a change that has occurred on disk
- * that needs us to take some action within Ente to synchronize with the user's
- * Ente collections.
- *
- * Events get added in two ways:
- *
- * - When the app starts, it reads the current state of files on disk and
- * compares that with its last known state to determine what all events it
- * missed. This is easier than it sounds as we have only two events: add and
- * remove.
- *
- * - When the app is running, it gets live notifications from our file system
- * watcher (from the Node.js layer) about changes that have happened on disk,
- * which the app then enqueues onto the event queue if they pertain to the
- * files we're interested in.
- */
interface WatchEvent {
- /** The action to take */
action: "upload" | "trash";
- /** The path of the root folder corresponding to the {@link FolderWatch}. */
folderPath: string;
- /** The name of the Ente collection the file belongs to. */
collectionName: string;
- /** The absolute path to the file under consideration. */
filePath: string;
}
-/**
- * A composite of multiple {@link WatchEvent}s that only differ in their
- * {@link filePath}.
- *
- * When processing events, we combine a run of events with the same
- * {@link action}, {@link folderPath} and {@link collectionName}. This allows us
- * to process all the affected {@link filePaths} in one shot.
- */
type ClubbedWatchEvent = Omit<WatchEvent, "filePath"> & { filePaths: string[] };
-/**
- * Determine which events we need to process to synchronize the watched on-disk
- * folders to their corresponding collections.
- */
const deduceEvents = async (watches: FolderWatch[]): Promise<WatchEvent[]> => {
const electron = ensureElectron();
const events: WatchEvent[] = [];
for (const watch of watches) {
- // Skip inaccessible folders (e.g., ejected external drives).
+ // An ejected drive must not look like an empty folder.
if (watch.isAccessible === false) {
log.info(
`Skipping sync for inaccessible folder ${watch.folderPath}`,
@@ -655,7 +490,6 @@ const deduceEvents = async (watches: FolderWatch[]): Promise<WatchEvent[]> => {
const filePaths = await electron.fs.findFiles(folderPath);
- // Files that are on disk but not yet synced.
for (const filePath of pathsToUpload(filePaths, watch))
events.push({
action: "upload",
@@ -664,7 +498,6 @@ const deduceEvents = async (watches: FolderWatch[]): Promise<WatchEvent[]> => {
filePath,
});
- // Previously synced files that are no longer on disk.
for (const filePath of pathsToRemove(filePaths, watch))
events.push({
action: "trash",
@@ -677,24 +510,12 @@ const deduceEvents = async (watches: FolderWatch[]): Promise<WatchEvent[]> => {
return events;
};
-/**
- * Filter out hidden files, non-media files, and previously synced or ignored
- * paths from {@link paths} to get the list of paths that need to be uploaded
- * to the Ente collection.
- */
const pathsToUpload = (paths: string[], watch: FolderWatch) =>
paths
- // Filter out files whose names begins with a dot.
.filter((path) => !basename(path).startsWith("."))
- // Filter out known non-media files.
.filter((path) => !shouldIgnoreForUpload(path))
- // Files that are on disk but not yet synced or ignored.
.filter((path) => !isSyncedOrIgnoredPath(path, watch));
-/**
- * Return the paths to previously synced files that are no longer on disk and so
- * must be removed from the Ente collection.
- */
const pathsToRemove = (paths: string[], watch: FolderWatch) =>
watch.syncedFiles
.map((f) => f.path)
@@ -711,12 +532,6 @@ const collectionNameForPath = (path: string, watch: FolderWatch) =>
const parentDirectoryName = (path: string) => basename(dirname(path));
-/**
- * Extensions of files that should not be uploaded from watch folders.
- *
- * These are common non-media file types that might be present in directories
- * containing photos and videos, but are not themselves media files.
- */
const ignoredExtensions = new Set([
"zip",
"rar",
@@ -738,13 +553,6 @@ const ignoredExtensions = new Set([
"db",
]);
-/**
- * Return `true` if the file at the given path should be ignored for uploads.
- *
- * This is used to filter out known non-media files from watch folders before
- * attempting to upload them. This prevents spurious "Skipped" messages and
- * error logs for files that we know beforehand are not photos or videos.
- */
const shouldIgnoreForUpload = (path: string): boolean => {
const extension = lowercaseExtension(path);
return extension !== undefined && ignoredExtensions.has(extension);
diff --git a/web/packages/base/blob-cache.ts b/web/packages/base/blob-cache.ts
index be5df87c9a..a7cabba3cf 100644
--- a/web/packages/base/blob-cache.ts
+++ b/web/packages/base/blob-cache.ts
@@ -4,85 +4,21 @@ const blobCacheNames = [
"thumbs",
"face-crops",
"space-media",
- // Desktop app only
+ // Desktop only.
"files",
] as const;
-/**
- * Namespaces into which our blob caches are divided
- *
- * Note that namespaces are just arbitrary (but predefined) strings to split the
- * cached data into "folders", so to speak.
- * */
export type BlobCacheNamespace = (typeof blobCacheNames)[number];
-/**
- * A namespaced blob cache.
- *
- * This cache is suitable for storing large amounts of data (entire files).
- *
- * To obtain a cache for a given namespace, use {@link openBlobCache}. To clear all
- * cached data (e.g. during logout), use {@link clearBlobCaches}.
- *
- * [Note: Caching files]
- *
- * The underlying implementation of the cache is different depending on the
- * runtime environment.
- *
- * * The preferred implementation, and the one that is used when we're running
- * in a browser, is to use the standard [Web
- * Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
- *
- * * However when running under Electron (when this code runs as part of our
- * desktop app), a custom OPFS based cache is used instead. This is because
- * Electron currently doesn't support using standard Web Cache API for data
- * served by a custom protocol handler (See this
- * [issue](https://github.com/electron/electron/issues/35033), and the
- * underlying restriction that comes from
- * [Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/cache_storage/cache.cc;l=83-87?q=%22Request%20scheme%20%27%22&ss=chromium))
- *
- * [OPFS](https://web.dev/articles/origin-private-file-system) stands for Origin
- * Private File System. It is a recent API that allows a web site to store
- * reasonably large amounts of data. One option (that may still become possible
- * in the future) was to always use OPFS for caching instead of this dual
- * implementation, however currently [Safari does not support writing to OPFS
- * outside of web
- * workers](https://webkit.org/blog/12257/the-file-system-access-api-with-origin-private-file-system/)
- * ([the WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=231706)), so it's
- * not trivial to use this as a full on replacement of the Web Cache in the
- * browser. So for now we go with this split implementation.
- */
export interface BlobCache {
- /**
- * Get the data corresponding to {@link key} (if found) from the cache.
- */
get: (key: string) => Promise<Blob | undefined>;
- /**
- * Check if there is an item corresponding to {@link key} in the cache.
- */
has: (key: string) => Promise<boolean>;
- /**
- * Add the given {@link key}-value ({@link blob}) pair to the cache.
- */
put: (key: string, blob: Blob) => Promise<void>;
- /**
- * Delete the blob corresponding to the given {@link key}.
- *
- * The returned promise resolves to `true` if a cache entry was found,
- * otherwise it resolves to `false`.
- * */
delete: (key: string) => Promise<boolean>;
}
const cachedCaches = new Map<BlobCacheNamespace, BlobCache>();
-/**
- * Return the {@link BlobCache} corresponding to the given {@link name}.
- *
- * This is a wrapper over {@link openBlobCache} that caches (pun intended) the
- * cache and returns the same one each time it is called with the same name.
- * It'll open the cache lazily the first time it is invoked.
- */
export const blobCache = async (
name: BlobCacheNamespace,
): Promise<BlobCache> => {
@@ -91,81 +27,18 @@ export const blobCache = async (
return c;
};
-/**
- * Create a new {@link BlobCache} corresponding to the given {@link name}.
- *
- * @param name One of the arbitrary but predefined namespaces of type
- * {@link BlobCacheNamespace} which group related data and allow us to use the
- * same key across namespaces.
- */
+// Electron's custom protocols cannot use Cache API, so desktop uses OPFS.
+// Browsers stay on Cache API because OPFS writes are not universally usable here.
export const openBlobCache = async (
name: BlobCacheNamespace,
): Promise<BlobCache> =>
isDesktop ? openOPFSCacheWeb(name) : openWebCache(name);
-/**
- * Delete all data in the cache corresponding to {@link name}.
- */
export const clearBlobCache = async (name: BlobCacheNamespace) => {
cachedCaches.delete(name);
return isDesktop ? clearOPFSCache(name) : caches.delete(name);
};
-/**
- * [Note: ArrayBuffer vs Blob vs Uint8Array]
- *
- * ArrayBuffers are in memory, while blobs are unreified, and can directly point
- * to on disk objects too.
- *
- * If we are just passing data around without necessarily needing to manipulate
- * it, and we already have a blob, it's best to just pass that blob. Further,
- * blobs also retains the file's encoding information , and are thus a layer
- * above array buffers which are just raw byte sequences.
- *
- * ArrayBuffers are not directly manipulatable, which is where some sort of a
- * typed array or a data view comes into the picture. The typed `Uint8Array` is
- * a common way.
- *
- * To convert from ArrayBuffer to Uint8Array,
- *
- * new Uint8Array(arrayBuffer)
- *
- * Blobs are immutable, but a usual scenario is storing an entire file in a
- * blob, and when the need comes to display it, we can obtain a URL for it using
- *
- * URL.createObjectURL(blob)
- *
- * Also note that a File is a Blob!
- *
- * To convert from a Blob to ArrayBuffer
- *
- * await blob.arrayBuffer()
- *
- * To convert from a Blob to Uint8Array, chain the two steps
- *
- * new Uint8Array(await blob.arrayBuffer())
- *
- * To convert from an ArrayBuffer or Uint8Array to Blob
- *
- * new Blob([arrayBuffer, andOrAnyArray, andOrstring])
- *
- * To convert from a Uint8Array/ArrayBuffer/Blob to a ReadableStream
- *
- * new Response(array).body
- * OR
- * new Blob([...]).stream()
- *
- * To convert from a stream to a string (or JSON)
- *
- * await new Response(stream).text()
- * await new Response(stream).json()
- *
- * Refs:
- * - https://github.com/yigitunallar/arraybuffer-vs-blob
- * - https://stackoverflow.com/questions/11821096/what-is-the-difference-between-an-arraybuffer-and-a-blob
- */
-
-/** An implementation of {@link BlobCache} using Web Cache APIs */
const openWebCache = async (name: BlobCacheNamespace) => {
const cache = await caches.open(name);
return {
@@ -179,17 +52,7 @@ const openWebCache = async (name: BlobCacheNamespace) => {
};
};
-/** An implementation of {@link BlobCache} using OPFS */
const openOPFSCacheWeb = async (name: BlobCacheNamespace) => {
- // While all major browsers support OPFS now, their implementations still
- // have various quirks. However, we don't need to handle all possible cases
- // and can just instead use the APIs and guarantees Chromium provides since
- // this code will only run in our Electron app (which'll use Chromium as the
- // renderer).
- //
- // So for our purpose, these can serve as the doc for what's available:
- // https://web.dev/articles/origin-private-file-system
-
const root = await navigator.storage.getDirectory();
const caches = await root.getDirectoryHandle("cache", { create: true });
const cache = await caches.getDirectoryHandle(name, { create: true });
@@ -234,11 +97,6 @@ const openOPFSCacheWeb = async (name: BlobCacheNamespace) => {
};
};
-/**
- * Delete all cached data, including cached caches.
- *
- * Meant for use during logout, to reset the state of the user's account.
- */
export const clearBlobCaches = async () => {
cachedCaches.clear();
return isDesktop ? clearOPFSCaches() : clearWebCaches();
diff --git a/web/packages/base/components/MiniDialog.tsx b/web/packages/base/components/MiniDialog.tsx
index a554270308..e862d5c266 100644
--- a/web/packages/base/components/MiniDialog.tsx
+++ b/web/packages/base/components/MiniDialog.tsx
@@ -15,141 +15,24 @@ import React, { useState } from "react";
import log from "../log";
import { InlineErrorIndicator } from "./ErrorIndicator";
-/**
- * Customize the contents of an {@link AttributedMiniDialog}.
- */
export interface MiniDialogAttributes {
- /**
- * The dialog's title.
- *
- * This will be usually be a string, but the prop accepts any React node to
- * allow passing a i18next <Trans /> component.
- */
title?: React.ReactNode;
- /**
- * An optional component shown next to the title.
- */
icon?: React.ReactNode;
- /**
- * The dialog's message.
- *
- * This will be usually be a string, but the prop accepts any React node to
- * allow passing a i18next <Trans /> component.
- */
message?: React.ReactNode;
- /**
- * If `true`, then the dialog cannot be closed (e.g. with the ESC key, or
- * clicking on the backdrop) except through one of the explicitly provided
- * actions.
- */
nonClosable?: boolean;
- /**
- * If `true`, then the dialog cannot be replaced by another dialog while it
- * is being displayed.
- *
- * The app uses a single component to render mini dialogs, and it is
- * possible that new dialog contents might preempt and replace contents in a
- * dialog that is already being shown. Usually if such preemption is
- * expected then both dialogs use differing mechanisms, but it can happen in
- * rare unforeseen cases.
- *
- * This flag allow a dialog to indicate that it should not be preempted, as
- * it contains some critical information.
- *
- * Use this flag sparingly.
- */
nonReplaceable?: boolean;
- /**
- * Customize the primary action button shown in the dialog.
- *
- * This is provided by boxes which serve as some sort of confirmation. If
- * not provided, only the {@link cancel} button is shown, unless that too is
- * explicitly disabled.
- */
continue?: {
- /**
- * The string to use as the label for the primary action button.
- *
- * Default is `t("ok")`.
- */
text?: string;
- /**
- * The color of the button.
- *
- * Default is "accent".
- */
color?: ButtonProps["color"];
- /**
- * If `true`, the primary action button is auto focused when the dialog
- * is opened, allowing the user to confirm just by pressing ENTER.
- */
autoFocus?: ButtonProps["autoFocus"];
- /**
- * The function to call when the user activates the button.
- *
- * If this function returns a promise, then an activity indicator will
- * be shown on the button until the promise settles.
- *
- * If this function is not provided, or if the function completes /
- * fulfills, then then the dialog is automatically closed.
- *
- * Otherwise (that is, if the provided function throws), the dialog
- * remains open, showing a generic error.
- *
- * That's quite a mouthful, here's a flowchart:
- *
- * - Not provided: Close
- * - Provided sync:
- * - Success: Close
- * - Failure: Remain open, showing generic error
- * - Provided async:
- * - Success: Close
- * - Failure: Remain open, showing generic error
- */
action?: () => void | Promise<void>;
};
- /**
- * Customize the secondary action button shown in the dialog.
- *
- * This is rarely needed. When provided, these attributes behave similar to
- * the {@link continue} attributes, except this button is shown below the
- * primary button.
- *
- * This is not supported when button direction is "row".
- */
secondary?: {
- /**
- * The string to use as the label for the secondary action button.
- *
- * Must be provided.
- */
text: string;
- /**
- * The color of the button.
- *
- * Default is "primary".
- */
color?: ButtonProps["color"];
- /**
- * The function to call when the user activates the button.
- *
- * The behaviour of this function is exactly the same as that of the
- * primary {@link action} provided via the {@link continue} attributes.
- */
action?: () => void | Promise<void>;
};
- /**
- * The string to use as the label for the cancel button.
- *
- * Default is `t("cancel")`.
- *
- * Set this to `false` to omit the cancel button altogether.
- *
- * The object form allows providing both the button title and the action
- * handler (synchronous). The dialog is always closed on clicks.
- */
cancel?: string | false | { text: string; action: () => void };
- /** The direction in which the buttons are stacked. Default is "column". */
buttonDirection?: "row" | "column";
}
@@ -158,14 +41,6 @@ type MiniDialogProps = Pick<DialogProps, "open"> & {
attributes?: MiniDialogAttributes;
};
-/**
- * A small, mostly predefined, MUI {@link Dialog} that can be used to notify the
- * user, or ask for confirmation before actions.
- *
- * The rendered dialog can be customized by modifying the {@link attributes}
- * prop. If you find yourself wanting to customize it further, consider either
- * using a {@link TitledMiniDialog} or {@link Dialog}.
- */
export const AttributedMiniDialog: React.FC<
React.PropsWithChildren<MiniDialogProps>
> = ({ open, onClose, attributes, children }) => {
@@ -184,7 +59,6 @@ export const AttributedMiniDialog: React.FC<
const handleClose: ModalProps["onClose"] = () => {
if (attributes.nonClosable) return;
- // Ignore modal close requests while processing the user request.
if (phase == "loading" || phase == "secondary-loading") return;
resetPhaseAndClose();
};
@@ -287,12 +161,7 @@ export const AttributedMiniDialog: React.FC<
>
{attributes.title && (
<DialogTitle
- sx={{
- "&&&": { padding: 0 },
- // Wrap the title to the next line if there
- // isn't sufficient space to make it fit in one.
- flexShrink: 1,
- }}
+ sx={{ "&&&": { padding: 0 }, flexShrink: 1 }}
>
{attributes.title}
</DialogTitle>
@@ -300,7 +169,7 @@ export const AttributedMiniDialog: React.FC<
{attributes.icon}
</Stack>
) : (
- <Box sx={{ height: "8px" }} /> /* Spacer */
+ <Box sx={{ height: "8px" }} />
)}
<DialogContent>
{attributes.message && (
@@ -338,31 +207,10 @@ export const AttributedMiniDialog: React.FC<
};
type TitledMiniDialogProps = Pick<DialogProps, "open" | "onClose" | "sx"> & {
- /**
- * The dialog's title.
- */
title?: React.ReactNode;
- /**
- * Optional max width of the underlying MUI {@link Paper}.
- *
- * Default: 360px (same as {@link AttributedMiniDialog}).
- */
paperMaxWidth?: string;
};
-/**
- * MiniDialog in a "shell" form.
- *
- * This is a {@link Dialog} for use at places which need more customization than
- * what {@link AttributedMiniDialog} provides, but wish to retain a similar look
- * and feel without duplicating code.
- *
- * It does three things:
- *
- * - Sets a fixed size and padding similar to {@link AttributedMiniDialog}.
- * - Takes the title as a prop, and wraps it in a {@link DialogTitle}.
- * - Wraps children in a scrollable {@link DialogContent}.
- */
export const TitledMiniDialog: React.FC<
React.PropsWithChildren<TitledMiniDialogProps>
> = ({ open, onClose, sx, paperMaxWidth, title, children }) => (
diff --git a/web/packages/base/components/RowButton.tsx b/web/packages/base/components/RowButton.tsx
index b1b21c7ff7..2da12d58a6 100644
--- a/web/packages/base/components/RowButton.tsx
+++ b/web/packages/base/components/RowButton.tsx
@@ -12,15 +12,9 @@ import React from "react";
import { ActivityIndicator } from "./mui/ActivityIndicator";
interface RowButtonGroupTitleProps {
- /**
- * An optional leading SvgIcon before the title.
- */
icon?: React.ReactNode;
}
-/**
- * A section title, meant to precede a {@link RowButtonGroup}.
- */
export const RowButtonGroupTitle: React.FC<
React.PropsWithChildren<RowButtonGroupTitleProps>
> = ({ children, icon }) => (
@@ -40,9 +34,6 @@ export const RowButtonGroupTitle: React.FC<
</Stack>
);
-/**
- * A short description text meant to come after a {@link RowButtonGroup}.
- */
export const RowButtonGroupHint: React.FC<React.PropsWithChildren> = ({
children,
}) => (
@@ -54,39 +45,19 @@ export const RowButtonGroupHint: React.FC<React.PropsWithChildren> = ({
</Typography>
);
-/**
- * A divider for buttons in a {@link RowButtonGroup}.
- */
export const RowButtonDivider = () => (
<Divider sx={{ "&&&": { mttty: 0 }, opacity: 0.4 }} />
);
-/**
- * A group of {@link RowButton}s that visually look together as a single
- * section.
- *
- * {@link RowButtonGroupTitle} can be used to provide a title for the entire
- * group, and {@link RowButtonGroupHint} can be used to provide a hint text that
- * follows the group.
- *
- * {@link RowButtonDivider} can be used to to separate the individual buttons in
- * the group.
- *
- * ---
- *
- * Note: {@link RowButtonGroup} is not designed to work with the "secondary"
- * variant of {@link RowButton}.
- */
+// Group styling only supports primary RowButtons.
export const RowButtonGroup = styled("div")(
({ theme }) => `
background-color: ${theme.vars.palette.fill.faint};
border-radius: 8px;
- /* Modify the RowButton style when it is placed inside a RowButtonGroup. */
& > button {
border-radius: 8px;
background-color: transparent;
}
- /* Need to retarget the disabled state with increased specificity. */
& > button.Mui-disabled {
background-color: transparent;
}
@@ -99,19 +70,11 @@ export const RowButtonGroup = styled("div")(
border-top-right-radius: 0;
}
& > button:hover {
- /* These fills are translucent and additive, and the RowButtonGroup
- already has a background, so pick a (transparent) color that gives us
- a similar outcome of the hover state as for a RowButton that is not
- inside a RowButtonGroup */
background-color: ${theme.vars.palette.fill.faintHover};
}
- /* Reset the border radius when showing focus outlines that will be added
- by the styles attached to FocusVisibleButton. */
& > button.Mui-focusVisible {
border-radius: 8px;
}
- /* Modify the outline offset added by FocusVisibleButton for a visual
- effect that fits better with these row buttons. */
& > button:active {
outline-offset: 0;
}
@@ -119,93 +82,17 @@ export const RowButtonGroup = styled("div")(
);
interface RowButtonProps {
- /**
- * Variants:
- *
- * - "primary" (default): A row button with a filled in background color.
- *
- * - "secondary": A row button without a fill.
- */
variant?: "primary" | "secondary";
- /**
- * Color of the row button.
- *
- * Semantically, this is similar to the "color" props for a MUI button,
- * except we only support two cases for this row button component:
- *
- * - "primary" (default): A row button that uses "text.base" as the color of
- * the text (and an appropriate background color, if needed, based on the
- * value of the {@link variant}).
- *
- * - "critical": A row button that uses "critical.main" as the color of the
- * text. The background fill, if any, will be the same as what "primary"
- * would've entailed.
- */
color?: "primary" | "critical";
- /**
- * Modify the font weight of the {@link label}, when label is a string.
- *
- * Default: "medium".
- */
fontWeight?: string | number;
- /**
- * If true, then the row button will be disabled.
- */
disabled?: boolean;
- /**
- * Called when the row button is activated (e.g. by a click).
- */
onClick: () => void;
- /**
- * Optional icon shown at the leading edge of the row button.
- *
- * This is usually an icon like an {@link SvgIcon}, but it can be any
- * arbitrary component, the row button does not make any assumptions as to
- * what this is.
- *
- * If it is an {@link SvgIcon}, the row button will size it appropriately.
- */
startIcon?: React.ReactNode;
- /**
- * Optional icon shown at the trailing edge of the row button.
- *
- * Similar to {@link startIcon} this can be any arbitrary component, though
- * usually it is an {@link SvgIcon} whose size the row button will set.
- */
endIcon?: React.ReactNode;
- /**
- * The label for the component.
- *
- * Usually this is expected to be a string, in which case it is wrapped up
- * in an appropriate {@link Typography} and shown on the row button. But it
- * can be an arbitrary react component too, to allow customizing its
- * appearance or otherwise modifying it in one off cases (it will be used as
- * it is and not wrapped in a {@link Typography} if it is not a string).
- */
label: React.ReactNode;
- /**
- * The text (or icon) to show alongside {@link label}, separated from it by
- * a bullet.
- *
- * This is usually expected to be a string, in which case it is wrapped in a
- * {@link Typography} component and styled with a muted text color before
- * being rendered.
- *
- * However, it can also be an {@link SvgIcon} (or any an arbitrary
- * component), though in terms of styling, only an {@link SvgIcon} usually
- * makes sense.
- *
- * Similar to {@link label}, it will not be wrapped in a {@link Typography}
- * if it is not a string.
- */
caption?: React.ReactNode;
}
-/**
- * A button that looks like a row in a group of options / choices.
- *
- * It can be used both standalone, or as part of a {@link RowButtonGroup}.
- */
export const RowButton: React.FC<RowButtonProps> = ({
variant = "primary",
color = "primary",
@@ -246,8 +133,6 @@ export const RowButton: React.FC<RowButtonProps> = ({
direction="row"
sx={{ gap: "4px", alignItems: "center" }}
>
- {/* Don't shrink the main label, instead let the
- caption grow into two lines if it needs to. */}
<Typography sx={{ flexShrink: 0 }}>
{label}
</Typography>
@@ -269,19 +154,13 @@ export const RowButton: React.FC<RowButtonProps> = ({
);
type RowButtonRootProps = ButtonProps & {
- // Prefix with "rb" to differentiate this from the "variant" prop of the MUI
- // button that we're styling.
rbVariant: RowButtonProps["variant"];
};
const RowButtonRoot = styled(FocusVisibleButton, {
shouldForwardProp: (prop) => prop != "rbVariant",
- // name: "MuiMenuItem",
})<React.PropsWithChildren<RowButtonRootProps>>(({ theme }) => ({
- // Remove button's default padding.
padding: 0,
- // Set the size of the any icons (SvgIcon instances) provided to us to make
- // them fit with the Typography within the button's content.
"& .MuiSvgIcon-root": { fontSize: "20px" },
variants: [
{
@@ -318,31 +197,11 @@ const CaptionTypography: React.FC<
);
interface RowSwitchProps {
- /**
- * The state of the contained {@link EnteSwitch}.
- */
checked?: boolean;
- /**
- * Called when the user activates the contained {@link EnteSwitch}.
- */
onClick: () => void;
- /**
- * The label for the component.
- *
- * Similar to the {@link label} prop for {@link RowButton}, but can only be
- * a string instead of an arbitrary component.
- */
label: string;
}
-/**
- * A row that visually looks similar to a {@link RowButton}, but instead of a
- * button is a normal {@link Typography} with a {@link EnteSwitch} at its
- * trailing edge.
- *
- * It only works (visually) when placed within a {@link RowButtonGroup} since
- * that is where it gets its background color from.
- */
export const RowSwitch: React.FC<RowSwitchProps> = ({
checked,
label,
@@ -366,34 +225,10 @@ export const RowSwitch: React.FC<RowSwitchProps> = ({
);
interface RowLabelProps {
- /**
- * Optional icon shown at the leading edge of the row button.
- *
- * This is usually an icon like an {@link SvgIcon}, but it can be any
- * arbitrary component, the row button does not make any assumptions as to
- * what this is.
- *
- * Unlike a {@link RowButton}, there is not sizing applied to it.
- */
startIcon?: React.ReactNode;
- /**
- * The label for the component.
- *
- * Similar to the {@link label} prop for {@link RowButton}, but can only be
- * a string instead of an arbitrary component.
- */
label: string;
}
-/**
- * A row that visually looks similar to a {@link RowButton}, but instead of a
- * button is a normal {@link Typography}.
- *
- * This is useful for creating non-interactive, static, labels.
- *
- * It only works (visually) when placed within a {@link RowButtonGroup} since
- * that is where it gets its background color from.
- */
export const RowLabel: React.FC<RowLabelProps> = ({ startIcon, label }) => (
<Stack
direction="row"
@@ -408,17 +243,12 @@ export const RowLabel: React.FC<RowLabelProps> = ({ startIcon, label }) => (
<Stack direction="row" sx={{ py: "14px", gap: "10px" }}>
{startIcon && startIcon}
<Box sx={{ px: "2px" }}>
- {/* Nb: Unlike the button, this has "regular" fontWeight. */}
<Typography>{label}</Typography>
</Box>
</Stack>
</Stack>
);
-/**
- * A variant of {@link ActivityIndicator} with defaults suitable to be used as the
- * {@link EndIcon} of a {@link RowButton}.
- */
export const RowButtonEndActivityIndicator: React.FC = () => (
<ActivityIndicator size="20px" sx={{ color: "stroke.muted" }} />
);
diff --git a/web/packages/base/components/utils/mui-theme.d.ts b/web/packages/base/components/utils/mui-theme.d.ts
index 1cdcdef9e2..ff58cb174c 100644
--- a/web/packages/base/components/utils/mui-theme.d.ts
+++ b/web/packages/base/components/utils/mui-theme.d.ts
@@ -1,62 +1,17 @@
import type { PaletteColor } from "@mui/material";
import React from "react";
-// Import the module augmentation that provides types for `theme.vars.*`.
import type {} from "@mui/material/themeCssVarsAugmentation";
-// Add new tokens to the Palette.
-//
-// https://mui.com/material-ui/customization/css-theme-variables/usage/#adding-new-theme-tokens
-
declare module "@mui/material/styles" {
- /**
- * Add new "background" color tokens, giving us:
- *
- * - background.default
- * - background.paper
- * - background.paper2
- * - background.elevatedPaper
- * - background.searchInput
- */
interface TypeBackground {
- /**
- * A second level elevation, indicating a paper within a paper.
- */
paper2: string;
- /**
- * The first among background.paper and background.paper2 that is not
- * the same as the default background.
- *
- * In light mode, background.default and background.paper are the same,
- * while in dark mode background.paper is already elevated. This
- * property can be used to obtain the first paper that is actually
- * elevated above the background irrespective of the theme.
- */
+ // First paper color elevated above default in either color scheme.
elevatedPaper: string;
- /**
- * Background color for the search input area.
- */
searchInput: string;
}
- /**
- * Define a new set of tokens for the "text" color in the palette which
- * matches the strength triads we use for stroke and fill.
- *
- * Since there is no way to override or replace the existing tokens, we can
- * only augment the interface with our new tokens. However, our code should
- * NOT use the default tokens provided by MUI:
- *
- * - text.primary <- Don't use
- * - text.secondary <- Don't use
- * - text.disabled <- Don't use
- *
- * Instead, use these three:
- *
- * - text.base
- * - text.muted
- * - text.faint
- */
+ // App code uses these instead of MUI's primary, secondary, and disabled.
interface TypeText {
base: string;
muted: string;
@@ -64,45 +19,9 @@ declare module "@mui/material/styles" {
}
interface Palette {
- /**
- * The main brand color. e.g. the "Ente green", the "Auth purple".
- *
- * This does not vary with the color scheme.
- */
accent: PaletteColor;
- /**
- * The color for potentially dangerous actions, errors, or other things
- * we would like to call the user's attention out to.
- *
- * MUI has an "error" palette color, but that seems to semantically not
- * gel with all uses. e.g. it feels weird to create a button with
- * color="error".
- *
- * This does not vary with the color scheme.
- */
critical: PaletteColor;
- /**
- * Neutral transparent colors for the stroke of icons and other outlines.
- *
- * These change with the color scheme.
- *
- * They come in three strengths which are meant to play nicely with the
- * corresponding strengths of "text.*" and "fill.*", and an extra
- * "fainter" variant for ad-hoc uses.
- */
stroke: { base: string; muted: string; faint: string; fainter: string };
- /**
- * Neutral transparent colors for filling small areas like icon or
- * button backgrounds.
- *
- * These change with the color scheme.
- *
- * They come in three strengths which are meant to play nicely with the
- * corresponding strengths of "text.*" and "stroke.*", plus extra ones.
- *
- * Some strengths also have a hover variant, useful to indicate hover on
- * buttons and menu items that use the corresponding fill.
- */
fill: {
base: string;
muted: string;
@@ -110,59 +29,16 @@ declare module "@mui/material/styles" {
faintHover: string;
fainter: string;
};
- /**
- * Transparent background fills that serve as the backdrop of modals,
- * dialogs and drawers etc.
- *
- * These change with the color scheme.
- */
backdrop: { base: string; muted: string; faint: string };
- /**
- * Various ad-hoc fixed colors used by our designs.
- *
- * These do not change with the color scheme.
- *
- * Some places in the code also use the grey PaletteColor provided by
- * MUI whose corresponding color values can be seen at
- * https://mui.com/material-ui/customization/default-theme/
- */
fixed: {
- /**
- * The color of a switch when it is enabled.
- */
switchOn: string;
- /**
- * A subset of the dark mode colors, fixed so that they don't change
- * even when the app is in light mode.
- */
dark: {
background: Omit<TypeBackground, "elevatedPaper">;
text: Omit<TypeText, "primary" | "secondary" | "disabled">;
divider: string;
};
};
- /**
- * MUI as of v6 does not allow customizing shadows easily. This is due
- * for change: https://github.com/mui/material-ui/issues/44291.
- *
- * Meanwhile use a custom variable. Since it is specific to the color
- * scheme, keep it inside the palette.
- */
- boxShadow: {
- /**
- * Drop shadow for the MUI {@link Paper}. In particular, this also
- * gets used as the drop shadow for {@link Dialog} (which uses a
- * {@link Paper} to embed its contents).
- */
- paper: string;
- /**
- * Drop shadow for the MUI {@link Menu} and other small floating
- * elements like the {@link Notification} {@link Snackbar}.
- */
- menu: string;
- /** Currently unused. */
- button: string;
- };
+ boxShadow: { paper: string; menu: string; button: string };
}
interface PaletteOptions {
@@ -176,17 +52,12 @@ declare module "@mui/material/styles" {
}
}
-// Make our custom palette colors available for use as the color prop of various
-// MUI components.
-
declare module "@mui/material/Button" {
interface ButtonPropsColorOverrides {
- // Turn off MUI provided palette colors we don't use.
error: false;
success: false;
info: false;
warning: false;
- // Add our custom palette colors.
accent: true;
critical: true;
}
@@ -194,7 +65,6 @@ declare module "@mui/material/Button" {
declare module "@mui/material/IconButton" {
interface IconButtonPropsColorOverrides {
- // Turn off MUI provided palette colors we don't use.
error: false;
success: false;
info: false;
@@ -226,10 +96,6 @@ declare module "@mui/material/CircularProgress" {
}
}
-// Tell TypeScript about our Typography variants
-//
-// https://mui.com/material-ui/customization/typography/#adding-amp-disabling-variants
-
declare module "@mui/material/styles" {
interface TypographyVariants {
body: React.CSSProperties;
@@ -247,9 +113,7 @@ declare module "@mui/material/styles" {
}
declare module "@mui/material/Typography" {
- // Update the Typography's variant prop options.
interface TypographyPropsVariantOverrides {
- // Turn off MUI provided variants we don't use.
subtitle1: false;
subtitle2: false;
body1: false;
@@ -257,7 +121,6 @@ declare module "@mui/material/Typography" {
caption: false;
button: false;
overline: false;
- // Add our custom variants.
body: true;
small: true;
mini: true;
diff --git a/web/packages/base/components/utils/theme.ts b/web/packages/base/components/utils/theme.ts
index 1427d1b8ef..0ca085c1b7 100644
--- a/web/packages/base/components/utils/theme.ts
+++ b/web/packages/base/components/utils/theme.ts
@@ -6,7 +6,6 @@ import type { AppName } from "ente-base/app";
const getTheme = (appName: AppName): Theme => {
const colors = getColors(appName);
const cs = getColorSchemes(colors);
- // Cast app should always be shown in dark.
const colorSchemes =
appName == "cast" ? { ...cs, light: cs.dark } : { ...cs };
return createTheme({
@@ -14,104 +13,11 @@ const getTheme = (appName: AppName): Theme => {
colorSchemes,
typography: getTypography(appName),
components: getComponents(appName),
- shape: {
- // Increase the default border radius multiplier from 4 to 8.
- borderRadius: 8,
- },
- transitions: {
- // Increase the default transition out duration from 195 to 300.
- duration: { leavingScreen: 300 },
- },
+ shape: { borderRadius: 8 },
+ transitions: { duration: { leavingScreen: 300 } },
});
};
-/**
- * [Note: Colors]
- *
- * The word "color" in MUI stands for different things. In particular, the color
- * prop for (e.g.) a Button is not the same as the color passed in the sx prop.
- *
- * There are three layers (only the first is necessary, rest are semantic):
- *
- * 1. Consider some color, say a shade of red. This will be represented by its
- * exact CSS color value, say "#ee0000".
- *
- * 2. These can be groups of color values that have roughly the same hue, but
- * different levels of saturation. Such hue groups are arranged together into
- * a "Colors" exported by "@mui/material":
- *
- * export interface Color {
- * 50: string;
- * 100: string;
- * ...
- * 800: string;
- * 900: string;
- * A100: string;
- * ...
- * A700: string;
- * }
- *
- * 3. Finally, there are "PaletteColors" (the naming of props, and
- * documentation within MUI (as of v6), omits the palette qualifier).
- *
- * export interface PaletteColor {
- * light: string;
- * main: string;
- * dark: string;
- * contrastText: string;
- * }
- *
- * The PaletteColors are what we use in the MUI component props (e.g. Button).
- * The PaletteColors are defined by providing color values for the four "tokens"
- * that make them up, either directly ("#aa000") or via Colors ("red[500]").
- *
- * Within the sx prop we need to specify a color value, which can come from the
- * palette. The "palette", as defined by the palette property we provide when
- * creating the theme, can consist of arbitrary (and nestable) key value pairs.
- *
- * Within sx prop, the "color" and "backgroundColor" props can refer to paths
- * inside this palette object. That is,
- *
- * sx={{ color: "foo.bar" }}
- *
- * resolves to theme.vars.palette.foo.bar.
- *
- * [Note: Color names]
- *
- * When defining color names, there is some attempt at trying to use MUI v6,
- * which uses MD (Material Design) v2, nomenclature when feasible (just to keep
- * the number of concepts low), but as such, our color names should not be
- * thought of as following Material Design, and should be treated as arbitrary
- * tokens reflecting our own design system.
- *
- * Some callouts:
- *
- * - Our "primary" and "secondary" are neutral grays instead of the two-tone
- * primary and secondary in MD. Our "accent" is corresponds to the MD primary.
- *
- * - Our "critical" is similar to and the alternative for the MD error (which is
- * not used).
- *
- * - Two of the other default MD PaletteColors - warning, success - are used
- * rarely, while info is not used at all.
- *
- * [Note: Theme and palette custom variables]
- *
- * Custom variables can be added to both the top level theme object, and to the
- * palette object within the theme. One would imagine that within the palette
- * there would only be colors that follow PaletteColor, but that's not something
- * MUI itself follows.
- *
- * So there is no particular reason to place custom color related variables in
- * theme vs in the palette. As a convention:
- *
- * - Custom colors (even if they're not PaletteColors) go within the palette.
- *
- * - Non-color tokens that depend on the color scheme (e.g. box shadows) also go
- * within the palette so that they can be made color scheme specific.
- *
- * - All other custom variables remain within the top level theme.
- */
const getColors = (appName: AppName) => ({
..._colors,
...{
@@ -164,13 +70,6 @@ const getColors = (appName: AppName) => ({
},
});
-/**
- * The color values.
- *
- * Use this arbitrarily shaped object to define the palette. This avoid
- * duplication across color schemes, and also helps see if there are any
- * reusable colors.
- */
const _colors = {
accentPhotos: { dark: "#00b33c", main: "#1db954", light: "#01de4d" },
accentAuth: { dark: "#8e0fcb", main: "#9610d6", light: "#8e2de2" },
@@ -334,7 +233,6 @@ const _colors = {
},
},
light: {
- // Keep these solid.
background: {
default: "#fff",
paper: "#fff",
@@ -358,9 +256,6 @@ const _colors = {
faintHover: "rgba(0 0 0 / 0.08)",
fainter: "rgba(0 0 0 / 0.02)",
},
- // MUI (as of v6.4) doesn't like it if we specify a non-solid color for
- // primary.main or secondary.main, or don't specify it using the #nnnnnn
- // notation; it seems to mess with the derivation of the color channels.
secondary: { main: "#f5f5f5", hover: "#e9e9e9" },
stroke: {
base: "#000",
@@ -421,6 +316,7 @@ const getColorSchemes = (colors: ReturnType<typeof getColors>) => ({
elevatedPaper: colors.light.background.paper2,
},
backdrop: colors.light.backdrop,
+ // MUI derives color channels only from solid #rrggbb values here.
primary: {
main: colors.fixed.black,
contrastText: colors.fixed.white,
@@ -445,15 +341,10 @@ const getColorSchemes = (colors: ReturnType<typeof getColors>) => ({
contrastText: colors.fixed.white,
},
text: {
- // Alias the tokens used by MUI to the ones that we use. This way,
- // we don't need to change the default ("primary"), or update the
- // MUI internal styling that refers to these tokens.
- //
- // Our own code should not use these.
+ // These aliases are for MUI internals; app code uses the tokens below.
primary: colors.light.text.base,
secondary: colors.light.text.muted,
disabled: colors.light.text.faint,
- // Our color tokens.
base: colors.light.text.base,
muted: colors.light.text.muted,
faint: colors.light.text.faint,
@@ -463,42 +354,20 @@ const getColorSchemes = (colors: ReturnType<typeof getColors>) => ({
divider: colors.light.stroke.faint,
fixed: colors.fixed,
boxShadow: colors.light.boxShadow,
- // Override some MUI defaults for styling action elements like
- // buttons and menu items.
- //
- // Nb: There are more where these came from, currently those don't
- // affect us, but in the future they might.
- //
- // https://github.com/mui/material-ui/blob/v6.4.0/packages/mui-material/src/styles/createPalette.js#L68
action: {
- // The color of an active action like an icon button.
active: colors.light.stroke.base,
- // The color of an hovered action.
hover: colors.light.fill.faintHover,
- // For an icon button, the hover background color is derived
- // from the active color above and this opacity. Use a value
- // that results in the same result as faintHover.
hoverOpacity: 0.08,
- // The color of a disabled action.
disabled: colors.light.text.faint,
- // The background color of a disabled action.
disabledBackground: colors.light.fill.faint,
},
- // Override some internal MUI defaults that impact the components
- // which we use.
- //
- // https://github.com/mui/material-ui/blob/v6.4.0/packages/mui-material/src/styles/createThemeWithVars.js#L271
FilledInput: {
bg: colors.light.fill.faint,
hoverBg: colors.light.fill.faintHover,
- // While we don't specifically have disabled inputs, TextInputs
- // do get disabled when the form is submitting, and this value
- // comes into play then.
disabledBg: colors.light.fill.fainter,
},
},
},
- // -- See the light mode section for comments
dark: {
palette: {
background: {
@@ -542,7 +411,6 @@ const getColorSchemes = (colors: ReturnType<typeof getColors>) => ({
divider: colors.dark.stroke.faint,
fixed: colors.fixed,
boxShadow: colors.dark.boxShadow,
- // -- See the light mode section for comments
action: {
active: colors.dark.stroke.base,
hover: colors.dark.fill.faintHover,
@@ -559,69 +427,18 @@ const getColorSchemes = (colors: ReturnType<typeof getColors>) => ({
},
});
-/**
- * [Note: Font weights]
- *
- * We only use three font weights:
- *
- * - 500 (sx "regular")
- * - 600 (sx "medium")
- * - 700 (sx "bold", CSS "bold")
- *
- * While the sx prop allows us to use keywords "regular", "medium" and "bold",
- * which we do elsewhere in the code, within this file those keywords cannot be
- * used in all contexts because they instead map to the CSS keywords. To avoid
- * any confusion, within this file we only use the numeric values.
- *
- * ---
- *
- * MUI (as of v6) uses the following font weights by default:
- *
- * - fontWeightLight 300
- * - fontWeightRegular 400
- * - fontWeightMedium 500
- * - fontWeightBold 700
- *
- * The browser default (CSS keyword "normal"), is also 400.
- *
- * However for Inter, the font that we use, 400 is too light, and to improve
- * legibility we change fontWeightRegular to 500.
- *
- * Correspondingly, we shift fontWeightMedium to 600. fontWeightBold then ends
- * up mapping back to 700, which also nicely coincides with the CSS keyword
- * "bold".
- *
- * MUI uses fontWeightLight only as the default font weight for the h1 and h2
- * variants, but we override their font weight in our theme. Thus we don't need
- * to bother with the light variant (though for consistency of specifying every
- * value, we alias it the same weight as regular, 500).
- */
const baseTypography: TypographyVariantsOptions = {
fontFamily: '"Inter Variable", sans-serif',
fontWeightLight: 500,
- fontWeightRegular: 500 /* CSS baseline reset sets this as the default */,
+ fontWeightRegular: 500,
fontWeightMedium: 600,
fontWeightBold: 700,
- h1: { fontSize: "48px", lineHeight: "58px", fontWeight: 600 /* Medium */ },
- h2: {
- fontSize: "32px",
- lineHeight: "39px",
- fontWeight: 500 /* Reset to regular to override MUI's default theme */,
- },
- h3: { fontSize: "24px", lineHeight: "29px", fontWeight: 600 /* Medium */ },
- h4: {
- fontSize: "22px",
- lineHeight: "27px",
- fontWeight: 500 /* Reset to regular to override MUI's default theme */,
- },
- h5: { fontSize: "20px", lineHeight: "25px", fontWeight: 600 /* Medium */ },
- // h6 is the default variant used by MUI's DialogTitle.
- h6: {
- // The font size and line height below is the same as large.
- fontSize: "18px",
- lineHeight: "22px",
- fontWeight: 600 /* Medium */,
- },
+ h1: { fontSize: "48px", lineHeight: "58px", fontWeight: 600 },
+ h2: { fontSize: "32px", lineHeight: "39px", fontWeight: 500 },
+ h3: { fontSize: "24px", lineHeight: "29px", fontWeight: 600 },
+ h4: { fontSize: "22px", lineHeight: "27px", fontWeight: 500 },
+ h5: { fontSize: "20px", lineHeight: "25px", fontWeight: 600 },
+ h6: { fontSize: "18px", lineHeight: "22px", fontWeight: 600 },
body: { fontSize: "16px", lineHeight: "20px" },
small: { fontSize: "14px", lineHeight: "17px" },
mini: { fontSize: "12px", lineHeight: "15px" },
@@ -634,7 +451,6 @@ const getTypography = (appName: AppName): TypographyVariantsOptions => {
...baseTypography,
fontFamily:
'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
- // Ensu-specific variants (type-augmented in web/apps/ensu/src/types).
message: { fontSize: "15px", lineHeight: "1.7", fontWeight: 400 },
code: {
fontSize: "13px",
@@ -648,40 +464,15 @@ const getTypography = (appName: AppName): TypographyVariantsOptions => {
return baseTypography;
};
-// Use the base typography for component style overrides (Button sizing, etc.).
const typography = baseTypography;
-/**
- * > [!NOTE]
- * >
- * > The theme isn't tree-shakeable, prefer creating new components for heavy
- * > customization.
- * >
- * > https://mui.com/material-ui/customization/theme-components/
- */
+// Theme overrides are bundled into every app; keep heavy customization local.
const components: Components = {
- MuiCssBaseline: {
- styleOverrides: {
- body: {
- // MUI has different letter spacing for each variant, but those
- // are values arrived at for the default Material font, and
- // don't work for the font that we're using.
- //
- // So we reset the letter spacing for _all_ variants to a
- // reasonable value that works for our font.
- letterSpacing: "-0.011em",
- },
- },
- },
+ MuiCssBaseline: { styleOverrides: { body: { letterSpacing: "-0.011em" } } },
MuiTypography: {
defaultProps: {
- // MUI has body1 as the default variant for Typography, but our
- // variant scheme is different, instead of body1/2, we have
- // large/body/small etc. So reset the default to our equivalent of
- // body1, which is "body".
variant: "body",
- // Map all our custom variants to <p>.
variantMapping: { body: "p", small: "p", mini: "p", tiny: "p" },
},
},
@@ -689,8 +480,7 @@ const components: Components = {
MuiModal: {
styleOverrides: {
root: {
- // A workaround to prevent stuck modals from blocking clicks.
- // https://github.com/mui/material-ui/issues/32286#issuecomment-1287951109
+ // Invisible stale modal roots must not block clicks.
'&:has(> div[style*="opacity: 0"])': { pointerEvents: "none" },
},
},
@@ -708,26 +498,7 @@ const components: Components = {
MuiDialog: {
defaultProps: {
- // [Note: Workarounds for unactionable ARIA warnings]
- //
- // This is required to prevent console warnings about aria-hiding a
- // focused button when the dialog is closed. e.g. Select a file,
- // delete it. On closing the confirmation dialog, the error appears.
- //
- // The default is supposed to already be false, but setting this
- // again seems to help. But sometimes we need to set this to `true`
- // to prevent the warning. And sometimes neither helps, and we need
- // to add random setTimeouts.
- //
- // Angular, Bootstrap, MUI, shadcn: all seem to be emitting these
- // warning (just search the web). I'm don't know if this is just
- // someone at Chrome deciding to emit spurious warnings without
- // understanding the flow, or if none of these libraries have
- // managed to implement the ARIA spec properly yet (which says more
- // about the spec than about the libraries).
- //
- // - https://issues.chromium.org/issues/392121909
- // - https://github.com/mui/material-ui/issues/43106#issuecomment-2314809028
+ // The explicit value suppresses aria-hidden focus warnings on close.
closeAfterTransition: false,
},
styleOverrides: {
@@ -735,35 +506,13 @@ const components: Components = {
".MuiBackdrop-root": {
backgroundColor: "var(--mui-palette-backdrop-muted)",
},
- // Reset the MUI default paddings to 16px everywhere.
- //
- // This is not a great choice either, usually most dialogs, for
- // one reason or the other, will need to customize this padding
- // anyway. But not resetting it to 16px leaves it at the MUI
- // defaults, which just doesn't work well with our designs.
- "& .MuiDialogTitle-root": {
- // MUI default is '16px 24px'.
- padding: "16px",
- },
+ "& .MuiDialogTitle-root": { padding: "16px" },
"& .MuiDialogContent-root": {
- // MUI default is '20px 24px'.
padding: "16px",
- // If the contents of the dialog's contents exceed the
- // available height, show a scrollbar just for the contents
- // instead of the entire dialog.
overflowY: "auto",
},
- "& .MuiDialogActions-root": {
- // MUI default is way off for us since they cluster the
- // buttons to the right, while our designs usually want the
- // buttons to align with the heading / content.
- padding: "16px",
- },
+ "& .MuiDialogActions-root": { padding: "16px" },
".MuiDialogTitle-root + .MuiDialogContent-root": {
- // MUI resets this to 0 when the content doesn't use
- // dividers (none of ours do). I feel that is a better
- // default, since unlike margins, padding doesn't collapse,
- // but changing this now would break existing layouts.
paddingTop: "16px",
},
},
@@ -775,36 +524,18 @@ const components: Components = {
root: {
variants: [
{
- // Use our "paper" shadow for elevated Paper.
props: { variant: "elevation" },
style: {
- // MUI applies a semi-transparent background image
- // for elevation in dark mode. Remove it to match
- // background for our designs.
backgroundImage: "none",
- // Use our paper shadow.
boxShadow: "var(--mui-palette-boxShadow-paper)",
},
},
- {
- // Undo the effects of variant "elevation" case above
- // case when elevation is 0.
- props: { elevation: 0 },
- style: { boxShadow: "none" },
- },
+ { props: { elevation: 0 }, style: { boxShadow: "none" } },
],
},
},
},
- // The default link "color" prop is "primary", which maps to "fill.base"
- // (and equivalently, to "text.base"). In our current designs, the <Link>
- // MUI component is only used in places where the surrounding text uses
- // "text.muted", so this default already provides it a highlight compared to
- // the text it in embedded in.
- //
- // We additionally disable the underline, and add a hover indication by
- // switching its color to the main accent.
MuiLink: {
defaultProps: { underline: "none" },
styleOverrides: {
@@ -813,21 +544,12 @@ const components: Components = {
},
MuiButton: {
- defaultProps: {
- // Change the default button variant from "text" to "contained".
- variant: "contained",
- // Disable shadows.
- disableElevation: true,
- },
+ defaultProps: { variant: "contained", disableElevation: true },
styleOverrides: {
- // We don't use the size prop for the MUI button, or rather it
- // cannot be used, since we have fixed the paddings and font sizes
- // unconditionally here (which is all that the size prop changes).
root: {
padding: "12px 16px",
borderRadius: "4px",
textTransform: "none",
- // Body, but medium.
fontSize: typography.body?.fontSize,
lineHeight: typography.body?.lineHeight,
fontWeight: 600,
@@ -840,15 +562,8 @@ const components: Components = {
MuiInputBase: {
styleOverrides: {
formControl: {
- // Give a symmetric border to the input field, by default the
- // border radius is only applied to the top for the "filled"
- // variant of input used inside TextFields.
borderRadius: "8px",
- // Clip the bottom border so that there is no gap between the
- // filled area and the (full width) border.
overflow: "hidden",
- // Hide the bottom border that always appears for the "filled"
- // variant of input used inside TextFields.
"::before": { borderBottom: "none !important" },
},
},
@@ -856,13 +571,8 @@ const components: Components = {
MuiTextField: {
defaultProps: {
- // The MUI default variant is "outlined", override it to use the
- // "filled" one by default.
variant: "filled",
- // Reduce the vertical margins that MUI adds to the TextField.
- //
- // Note that this causes things to be too tight when the helper text
- // is shown, so this is not recommended for new code that we write.
+ // Dense margins are too tight with helper text; override them there.
margin: "dense",
},
styleOverrides: {
@@ -871,14 +581,8 @@ const components: Components = {
},
MuiCheckbox: {
- defaultProps: {
- // Disable the ripple effect for all checkboxes.
- disableRipple: true,
- },
+ defaultProps: { disableRipple: true },
styleOverrides: {
- // Since we've disabled the ripple, add other affordances to it (a
- // background and outline) to clearly indicate whenever it gains
- // keyboard focus.
root: {
"&.Mui-focusVisible": {
backgroundColor: "var(--mui-palette-fill-faint)",
@@ -934,22 +638,9 @@ const components: Components = {
},
},
- MuiSnackbar: {
- styleOverrides: {
- root: {
- // Set a default border radius for all snackbar's (e.g.
- // notification popups).
- borderRadius: "8px",
- },
- },
- },
+ MuiSnackbar: { styleOverrides: { root: { borderRadius: "8px" } } },
- MuiAlert: {
- defaultProps: {
- // Use the outlined variant by default (instead of "standard").
- variant: "outlined",
- },
- },
+ MuiAlert: { defaultProps: { variant: "outlined" } },
};
const getComponents = (appName: AppName): Components => {
@@ -1083,37 +774,14 @@ const getComponents = (appName: AppName): Components => {
};
};
-// Exports ---
-
-/**
- * The MUI {@link Theme} to use for the photos app.
- *
- * This is also the "default" theme, in that it is used for the accounts app
- * which serves both photos and auth.
- */
export const photosTheme = getTheme("photos");
-/**
- * The MUI {@link Theme} to use for the auth app.
- */
export const authTheme = getTheme("auth");
-/**
- * The MUI {@link Theme} to use for the cast app.
- *
- * This is the same as the dark theme for the photos app.
- */
export const castTheme = getTheme("cast");
-/**
- * The MUI {@link Theme} to use for the Ensu app.
- */
export const ensuTheme = getTheme("ensu");
-/**
- * The MUI {@link Theme} to use for the locker public app.
- */
export const shareTheme = getTheme("share");
-/** Theme for the locker app (blue accent, matching mobile Locker app). */
export const lockerTheme = getTheme("locker");
diff --git a/web/packages/base/crypto/index.ts b/web/packages/base/crypto/index.ts
index dc629ec727..f59b199415 100644
--- a/web/packages/base/crypto/index.ts
+++ b/web/packages/base/crypto/index.ts
@@ -1,91 +1,7 @@
-/**
- * @file Cryptographic operations. This is the highest layer of the crypto code
- * hierarchy, and is meant to be used directly by the rest of our code.
- *
- * --|
- * --> For each function, more detailed documentation is in `libsodium.ts` <-
- * --|
- *
- * [Note: Crypto code hierarchy]
- *
- * 1. ente-base/crypto (Crypto API for our code)
- * 2. ente-base/crypto/libsodium (The actual implementation)
- * 3. libsodium-wrappers (JavaScript bindings to libsodium)
- *
- * Our cryptography primitives are provided by libsodium, specifically, its
- * JavaScript bindings ("libsodium-wrappers"). That is the lowest layer.
- *
- * > Note that we use the sumo variant, "libsodium-wrappers-sumo", since the
- * standard variant does not provide the `crypto_pwhash_*` functions.
- *
- * Direct usage of "libsodium-wrappers" is restricted to `crypto/libsodium.ts`.
- * That is the next higher layer. Usually the functions in this file are thin
- * wrappers over the raw libsodium APIs, with a bit of massaging. They also
- * ensure that sodium.ready has been called before accessing libsodium's APIs,
- * thus all the functions it exposes are async.
- *
- * Direct usage of "libsodium-wrappers" is restricted to this file,
- * `crypto/index.ts`. This is the highest layer. These are direct proxies to
- * functions exposed by `crypto/libsodium.ts`, but they automatically defer to a
- * worker thread if we're not already running on one. More on this below.
- *
- * ---
- *
- * [Note: Using libsodium in worker thread]
- *
- * This file, `crypto/index.ts`, and `crypto/worker.ts` are mostly logic-less
- * trampolines meant to allow us to seamlessly use the the same API both from
- * the main thread or from a web worker whilst ensuring that the implementation
- * never runs on the main thread.
- *
- * Cryptographic operations like encryption are CPU intensive and would cause
- * the UI to stutter if used directly on the main thread. To keep the UI smooth,
- * we instead want to run them in a web worker. However, sometimes we already
- * _are_ running in a web worker, and delegating to another worker is wasteful.
- *
- * The external API functions provided by this file check to see if we're
- * already in a web worker, and if so directly invoke the implementation.
- * Otherwise the call the sibling function in a shared "crypto" web worker
- * (which then invokes the implementation function, but this time in the context
- * of a web worker).
- *
- * As a consumer, it is safe to just call functions in this file, and they'll
- * just do the right thing based on the context. However, it is also fine to
- * explicitly get an handle to a crypto web worker and use that. e.g., the
- * uploader creates it own crypto worker instances and directly calls the
- * functions in the workers that it created instead of going through this file.
- *
- * ---
- *
- * [Note: Crypto layer API data types]
- *
- * There are two primary types used when exchanging data with these functions:
- *
- * 1. Base64 strings. Unless stated otherwise, all strings are taken as base64
- * encoded representations of the underlying data. Usually, the unqualified
- * function deals with base64 strings, since they also are the data type in
- * which we usually store and send the data.
- *
- * 2. Raw bytes. Uint8Arrays are byte arrays. The functions that deal with bytes
- * are usually indicated by a *Bytes suffix in their name, but not always
- * since it might also be the natural choice for functions that deal with
- * larger amounts of data.
- *
- * Where relevant and useful, functions also accept a union of these two - a
- * {@link BytesOrB64} where the implementation will automatically convert
- * to/from base64 to bytes if needed, thus saving on unnecessary conversions at
- * the caller side.
- *
- * Apart from these two, there are other secondary, one off types.
- *
- * 1. Hex representations of the bytes. These are indicated by the *Hex suffix
- * on the functions dealing with them.
- *
- * 2. JSON values. These are indicated by the *JSON suffix on the functions
- * dealing with them.
- */
import { ComlinkWorker } from "ente-base/worker/comlink-worker";
import { inWorker } from "../env";
+// Main-thread callers must use this module.
+// Call libsodium directly only from a worker.
import * as libsodium from "./libsodium";
import type {
BytesOrB64,
@@ -103,69 +19,37 @@ import type {
} from "./types";
import type { CryptoWorker } from "./worker";
-/**
- * Cached instance of the {@link ComlinkWorker} that wraps our web worker.
- */
let _comlinkWorker: ComlinkWorker<typeof CryptoWorker> | undefined;
-/**
- * Lazily created, cached, instance of a "shared" CryptoWorker web worker.
- *
- * Some code which needs to do operations in parallel (e.g. during the upload
- * flow) creates its own CryptoWorker web workers. But those are exceptions; the
- * rest of the code normally calls the functions in this file, and they all
- * implicitly use a default "shared" web worker (unless we're already running in
- * the context of a web worker).
- */
const sharedWorker = () =>
(_comlinkWorker ??= createComlinkCryptoWorker()).remote;
-/**
- * Create a new instance of a comlink worker that wraps a {@link CryptoWorker}
- * web worker.
- */
export const createComlinkCryptoWorker = () =>
new ComlinkWorker<typeof CryptoWorker>(
"crypto",
new Worker(new URL("worker.ts", import.meta.url)),
);
-/**
- * Convert bytes ({@link Uint8Array}) to a base64 string.
- */
export const toB64 = (bytes: Uint8Array): Promise<string> =>
inWorker()
? libsodium.toB64(bytes)
: sharedWorker().then((w) => w.toB64(bytes));
-/**
- * Convert a base64 string to bytes ({@link Uint8Array}).
- */
export const fromB64 = (b64String: string): Promise<Uint8Array> =>
inWorker()
? libsodium.fromB64(b64String)
: sharedWorker().then((w) => w.fromB64(b64String));
-/**
- * URL safe variant of {@link toB64}.
- */
export const toB64URLSafe = (bytes: Uint8Array): Promise<string> =>
inWorker()
? libsodium.toB64URLSafe(bytes)
: sharedWorker().then((w) => w.toB64URLSafe(bytes));
-/**
- * URL safe variant of {@link toB64} that does not add any padding ("="
- * characters).
- */
export const toB64URLSafeNoPadding = (bytes: Uint8Array): Promise<string> =>
inWorker()
? libsodium.toB64URLSafeNoPadding(bytes)
: sharedWorker().then((w) => w.toB64URLSafeNoPadding(bytes));
-/**
- * URL safe unpadded variant of {@link fromB64}.
- */
export const fromB64URLSafeNoPadding = (
b64String: string,
): Promise<Uint8Array> =>
@@ -173,55 +57,26 @@ export const fromB64URLSafeNoPadding = (
? libsodium.fromB64URLSafeNoPadding(b64String)
: sharedWorker().then((w) => w.fromB64URLSafeNoPadding(b64String));
-/**
- * Convert a base64 string to the hex representation of the underlying bytes.
- */
export const toHex = (b64String: string): Promise<string> =>
inWorker()
? libsodium.toHex(b64String)
: sharedWorker().then((w) => w.toHex(b64String));
-/**
- * Convert a hex string to the base64 representation of the underlying bytes.
- */
export const fromHex = (hexString: string): Promise<string> =>
inWorker()
? libsodium.fromHex(hexString)
: sharedWorker().then((w) => w.fromHex(hexString));
-/**
- * Return a new randomly generated 256-bit key (as a base64 string).
- *
- * The returned key is suitable for use with the *Box encryption functions, and
- * as a general encryption key (e.g. as the user's master key or recovery key).
- */
export const generateKey = (): Promise<string> =>
inWorker()
? libsodium.generateKey()
: sharedWorker().then((w) => w.generateKey());
-/**
- * Return a new randomly generated 256-bit key (as a base64 string) suitable for
- * use with the *Blob or *Stream encryption functions.
- */
export const generateBlobOrStreamKey = (): Promise<string> =>
inWorker()
? libsodium.generateBlobOrStreamKey()
: sharedWorker().then((w) => w.generateBlobOrStreamKey());
-/**
- * Encrypt the given data, returning a box containing the encrypted data and a
- * randomly generated nonce that was used during encryption.
- *
- * Both the encrypted data and the nonce are returned as base64 strings.
- *
- * Use {@link decryptBox} to decrypt the result.
- *
- * > The suffix "Box" comes from the fact that it uses the so called secretbox
- * > APIs provided by libsodium under the hood.
- * >
- * > See: [Note: 3 forms of encryption (Box | Blob | Stream)]
- */
export const encryptBox = (
data: BytesOrB64,
key: BytesOrB64,
@@ -230,20 +85,6 @@ export const encryptBox = (
? libsodium.encryptBox(data, key)
: sharedWorker().then((w) => w.encryptBox(data, key));
-/**
- * Encrypt the given data, returning a blob containing the encrypted data and a
- * decryption header as base64 strings.
- *
- * This function is usually used to encrypt data associated with an Ente object
- * (file, collection, entity) using the object's key.
- *
- * Use {@link decryptBlob} or {@link decryptBlobBytes} to decrypt the result.
- *
- * > The suffix "Blob" comes from our convention of naming functions that use
- * > the secretstream APIs without breaking the data into chunks.
- * >
- * > See: [Note: 3 forms of encryption (Box | Blob | Stream)]
- */
export const encryptBlob = (
data: BytesOrB64,
key: BytesOrB64,
@@ -252,12 +93,6 @@ export const encryptBlob = (
? libsodium.encryptBlob(data, key)
: sharedWorker().then((w) => w.encryptBlob(data, key));
-/**
- * A variant of {@link encryptBlob} that returns the result components as bytes
- * instead of as base64 strings.
- *
- * Use {@link decryptBlob} or {@link decryptBlobBytes} to decrypt the result.
- */
export const encryptBlobBytes = (
data: BytesOrB64,
key: BytesOrB64,
@@ -266,26 +101,6 @@ export const encryptBlobBytes = (
? libsodium.encryptBlobBytes(data, key)
: sharedWorker().then((w) => w.encryptBlobBytes(data, key));
-/**
- * Encrypt the JSON metadata associated with an Ente object (file, collection or
- * entity) using the object's key.
- *
- * This is a variant of {@link encryptBlob} tailored for encrypting any
- * arbitrary metadata associated with an Ente object. For example, it is used
- * for encrypting the various metadata fields associated with a file, using that
- * file's key.
- *
- * Instead of raw bytes, it takes as input an arbitrary JSON object which it
- * encodes into a string, and encrypts that.
- *
- * Use {@link decryptMetadataJSON} to decrypt the result.
- *
- * @param jsonValue The JSON value to encrypt. This can be an arbitrary JSON
- * value, but since TypeScript currently doesn't have a native JSON type, it is
- * typed as {@link unknown}.
- *
- * @param key The encryption key.
- */
export const encryptMetadataJSON = (
jsonValue: unknown,
key: BytesOrB64,
@@ -294,10 +109,6 @@ export const encryptMetadataJSON = (
? libsodium.encryptMetadataJSON(jsonValue, key)
: sharedWorker().then((w) => w.encryptMetadataJSON(jsonValue, key));
-/**
- * Encrypt the given data using chunked streaming encryption, but process all
- * the chunks in one go.
- */
export const encryptStreamBytes = (
data: Uint8Array,
key: BytesOrB64,
@@ -306,9 +117,6 @@ export const encryptStreamBytes = (
? libsodium.encryptStreamBytes(data, key)
: sharedWorker().then((w) => w.encryptStreamBytes(data, key));
-/**
- * Prepare for chunked streaming encryption using {@link encryptStreamChunk}.
- */
export const initChunkEncryption = (
key: BytesOrB64,
): Promise<InitChunkEncryptionResult> =>
@@ -316,9 +124,6 @@ export const initChunkEncryption = (
? libsodium.initChunkEncryption(key)
: sharedWorker().then((w) => w.initChunkEncryption(key));
-/**
- * Encrypt a chunk as part of a chunked streaming encryption.
- */
export const encryptStreamChunk = (
data: Uint8Array,
state: SodiumStateAddress,
@@ -330,10 +135,6 @@ export const encryptStreamChunk = (
w.encryptStreamChunk(data, state, isFinalChunk),
);
-/**
- * Decrypt a box encrypted using {@link encryptBox} and returns the decrypted
- * bytes as a base64 string.
- */
export const decryptBox = (
box: EncryptedBox,
key: BytesOrB64,
@@ -342,10 +143,6 @@ export const decryptBox = (
? libsodium.decryptBox(box, key)
: sharedWorker().then((w) => w.decryptBox(box, key));
-/**
- * Variant of {@link decryptBox} that returns the decrypted bytes as it is
- * (without encoding them to base64).
- */
export const decryptBoxBytes = (
box: EncryptedBox,
key: BytesOrB64,
@@ -354,10 +151,6 @@ export const decryptBoxBytes = (
? libsodium.decryptBoxBytes(box, key)
: sharedWorker().then((w) => w.decryptBoxBytes(box, key));
-/**
- * Decrypt a blob encrypted using either {@link encryptBlobBytes} or
- * {@link encryptBlob} and return it as a base64 encoded string.
- */
export const decryptBlob = (
blob: EncryptedBlob,
key: BytesOrB64,
@@ -366,10 +159,6 @@ export const decryptBlob = (
? libsodium.decryptBlob(blob, key)
: sharedWorker().then((w) => w.decryptBlob(blob, key));
-/**
- * A variant of {@link decryptBlobBytes} that returns the result bytes directly
- * (instead of encoding them as a base64 string).
- */
export const decryptBlobBytes = (
blob: EncryptedBlob,
key: BytesOrB64,
@@ -378,9 +167,6 @@ export const decryptBlobBytes = (
? libsodium.decryptBlobBytes(blob, key)
: sharedWorker().then((w) => w.decryptBlobBytes(blob, key));
-/**
- * Decrypt the result of {@link encryptStreamBytes}.
- */
export const decryptStreamBytes = (
file: EncryptedFile,
key: BytesOrB64,
@@ -389,10 +175,6 @@ export const decryptStreamBytes = (
? libsodium.decryptStreamBytes(file, key)
: sharedWorker().then((w) => w.decryptStreamBytes(file, key));
-/**
- * Prepare to decrypt the encrypted result produced using {@link initChunkEncryption} and
- * {@link encryptStreamChunk}.
- */
export const initChunkDecryption = (
header: string,
key: BytesOrB64,
@@ -401,11 +183,6 @@ export const initChunkDecryption = (
? libsodium.initChunkDecryption(header, key)
: sharedWorker().then((w) => w.initChunkDecryption(header, key));
-/**
- * Decrypt an individual chunk produced by {@link encryptStreamChunk}.
- *
- * This function is used in tandem with {@link initChunkDecryption}.
- */
export const decryptStreamChunk = (
data: Uint8Array,
state: SodiumStateAddress,
@@ -414,12 +191,6 @@ export const decryptStreamChunk = (
? libsodium.decryptStreamChunk(data, state)
: sharedWorker().then((w) => w.decryptStreamChunk(data, state));
-/**
- * Decrypt the metadata JSON encrypted using {@link encryptMetadataJSON}.
- *
- * @returns The decrypted JSON value. Since TypeScript does not have a native
- * JSON type, we need to return it as an `unknown`.
- */
export const decryptMetadataJSON = (
blob: EncryptedBlob,
key: BytesOrB64,
@@ -428,25 +199,16 @@ export const decryptMetadataJSON = (
? libsodium.decryptMetadataJSON(blob, key)
: sharedWorker().then((w) => w.decryptMetadataJSON(blob, key));
-/**
- * Generate a new public/private keypair.
- */
export const generateKeyPair = (): Promise<KeyPair> =>
inWorker()
? libsodium.generateKeyPair()
: sharedWorker().then((w) => w.generateKeyPair());
-/**
- * Public key encryption.
- */
export const boxSeal = (data: string, publicKey: string): Promise<string> =>
inWorker()
? libsodium.boxSeal(data, publicKey)
: sharedWorker().then((w) => w.boxSeal(data, publicKey));
-/**
- * Decrypt the result of {@link boxSeal}.
- */
export const boxSealOpen = (
encryptedData: string,
keyPair: KeyPair,
@@ -455,10 +217,6 @@ export const boxSealOpen = (
? libsodium.boxSealOpen(encryptedData, keyPair)
: sharedWorker().then((w) => w.boxSealOpen(encryptedData, keyPair));
-/**
- * Variant of {@link boxSealOpen} that returns the decrypted bytes as it is
- * (without encoding them to base64).
- */
export const boxSealOpenBytes = (
encryptedData: string,
keyPair: KeyPair,
@@ -469,20 +227,11 @@ export const boxSealOpenBytes = (
w.boxSealOpenBytes(encryptedData, keyPair),
);
-/**
- * Return a new randomly generated 128-bit salt (as a base64 string).
- *
- * The returned salt is suitable for use with {@link deriveKey}, and also as a
- * general 128-bit salt.
- */
export const generateDeriveKeySalt = (): Promise<string> =>
inWorker()
? libsodium.generateDeriveKeySalt()
: sharedWorker().then((w) => w.generateDeriveKeySalt());
-/**
- * Derive a key by hashing the given {@link passphrase} using Argon 2id.
- */
export const deriveKey = (
passphrase: string,
salt: string,
@@ -495,17 +244,11 @@ export const deriveKey = (
w.deriveKey(passphrase, salt, opsLimit, memLimit),
);
-/**
- * Derive a sensitive key from the given {@link passphrase}.
- */
export const deriveSensitiveKey = (passphrase: string): Promise<DerivedKey> =>
inWorker()
? libsodium.deriveSensitiveKey(passphrase)
: sharedWorker().then((w) => w.deriveSensitiveKey(passphrase));
-/**
- * Derive an key suitable for interactive use from the given {@link passphrase}.
- */
export const deriveInteractiveKey = (
passphrase: string,
): Promise<DerivedKey> =>
@@ -513,20 +256,11 @@ export const deriveInteractiveKey = (
? libsodium.deriveInteractiveKey(passphrase)
: sharedWorker().then((w) => w.deriveInteractiveKey(passphrase));
-/**
- * Derive a key suitable for moderate-cost password gates from the given
- * {@link passphrase}.
- */
export const deriveModerateKey = (passphrase: string): Promise<DerivedKey> =>
inWorker()
? libsodium.deriveModerateKey(passphrase)
: sharedWorker().then((w) => w.deriveModerateKey(passphrase));
-/**
- * Derive a subkey of the given {@link key} using the specified parameters.
- *
- * @returns the bytes of the derived subkey.
- */
export const deriveSubKeyBytes = async (
key: string,
subKeyLength: number,
diff --git a/web/packages/base/crypto/libsodium.ts b/web/packages/base/crypto/libsodium.ts
index 5df176e3e6..7902eedac0 100644
--- a/web/packages/base/crypto/libsodium.ts
+++ b/web/packages/base/crypto/libsodium.ts
@@ -1,13 +1,3 @@
-/**
- * @file A thin-ish layer over the actual libsodium APIs, to make them more
- * palatable to the rest of our Javascript code.
- *
- * All functions are stateless, async, and safe to use in Web Workers.
- *
- * Docs for the JS library: https://github.com/jedisct1/libsodium.js.
- *
- * To see where this code fits, see [Note: Crypto code hierarchy].
- */
import { ensureArrayBufferBacked } from "ente-base/bytes";
import { mergeUint8Arrays } from "ente-utils/array";
import sodium from "libsodium-wrappers-sumo";
@@ -28,21 +18,11 @@ import {
type SodiumStateAddress,
} from "./types";
-/**
- * Convert bytes ({@link Uint8Array}) to a base64 string.
- *
- * See also {@link toB64URLSafe} and {@link toB64URLSafeNoPadding}.
- */
export const toB64 = async (input: Uint8Array) => {
await sodium.ready;
return sodium.to_base64(input, sodium.base64_variants.ORIGINAL);
};
-/**
- * Convert a base64 string to bytes ({@link Uint8Array}).
- *
- * This is the converse of {@link toBase64}.
- */
export const fromB64 = async (
input: string,
): Promise<Uint8Array<ArrayBuffer>> => {
@@ -52,42 +32,16 @@ export const fromB64 = async (
);
};
-/**
- * Convert bytes ({@link Uint8Array}) to a URL-safe base64 string.
- *
- * See also {@link toB64URLSafe} and {@link toB64URLSafeNoPadding}.
- */
export const toB64URLSafe = async (input: Uint8Array) => {
await sodium.ready;
return sodium.to_base64(input, sodium.base64_variants.URLSAFE);
};
-/**
- * Convert bytes ({@link Uint8Array}) to a unpadded URL-safe base64 string.
- *
- * This differs from {@link toB64URLSafe} in that it does not append any
- * trailing padding character(s) "=" to make the resultant string's length be an
- * integer multiple of 4.
- *
- * - In some contexts, for example when serializing WebAuthn binary for
- * transmission over the network, this is the required / recommended approach.
- *
- * - In other cases, for example when trying to pass an arbitrary JSON string
- * via a URL parameter, this is also convenient so that we do not have to deal
- * with any ambiguity surrounding the "=" which is also the query parameter
- * key value separator.
- */
export const toB64URLSafeNoPadding = async (input: Uint8Array) => {
await sodium.ready;
return sodium.to_base64(input, sodium.base64_variants.URLSAFE_NO_PADDING);
};
-/**
- * Convert a unpadded URL-safe base64 string to bytes ({@link Uint8Array}).
- *
- * This is the converse of {@link toB64URLSafeNoPadding}, and does not expect
- * its input string's length to be a an integer multiple of 4.
- */
export const fromB64URLSafeNoPadding = async (
input: string,
): Promise<Uint8Array<ArrayBuffer>> => {
@@ -97,173 +51,29 @@ export const fromB64URLSafeNoPadding = async (
);
};
-/**
- * Convert a base64 string to the hex representation of the bytes that the base
- * 64 string encodes.
- *
- * Use {@link fromHex} to go back.
- */
export const toHex = async (input: string) => {
await sodium.ready;
return sodium.to_hex(await fromB64(input));
};
-/**
- * Convert a hex string to the base64 representation of the bytes that the hex
- * string encodes.
- *
- * This is the inverse of {@link toHex}.
- */
export const fromHex = async (input: string): Promise<string> => {
await sodium.ready;
return await toB64(sodium.from_hex(input));
};
-/**
- * If the provided {@link bob} ("Bytes or B64 string") is already a
- * {@link Uint8Array}, return it unchanged, otherwise convert the base64 string
- * into bytes and return those.
- */
const bytes = async (bob: BytesOrB64) =>
typeof bob == "string" ? fromB64(bob) : bob;
-/**
- * Generate a new randomly generated 256-bit key for use as a general encryption
- * key and return its base64 string representation.
- *
- * From the architecture docs:
- *
- * > [`crypto_secretbox_keygen`](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes)
- * > is used to generate all random keys within the application. Your
- * > `masterKey`, `recoveryKey`, `collectionKey`, `fileKey` are all 256-bit keys
- * > generated using this API.
- *
- * {@link generateKey} can be contrasted with {@link generateBlobOrStreamKey}
- * and can be thought of as a hypothetical "generateBoxKey". That is, the key
- * returned by this function is suitable for being used with the *Box encryption
- * functions (which eventually delegate to the libsodium's secretbox APIs).
- *
- * While this is a reasonable semantic distinction, in terms of implementation
- * there is no difference: currently both {@link generateKey} (or the
- * hypothetical "generateBoxKey") and {@link generateBlobOrStreamKey} produce
- * 256-bits of entropy that does not have any ties to a particular algorithm.
- *
- * @returns A new randomly generated 256-bit key (as a base64 string).
- */
export const generateKey = async () => {
await sodium.ready;
return toB64(sodium.crypto_secretbox_keygen());
};
-/**
- * Generate a new key for use with the *Blob or *Stream encryption functions,
- * and return its base64 string representation.
- *
- * This returns a new randomly generated 256-bit key (as a base64 string)
- * suitable for being used with libsodium's secretstream APIs.
- */
export const generateBlobOrStreamKey = async () => {
await sodium.ready;
return toB64(sodium.crypto_secretstream_xchacha20poly1305_keygen());
};
-/**
- * Encrypt the given data using libsodium's secretbox APIs, using a randomly
- * generated nonce.
- *
- * Use {@link decryptBox} or {@link decryptBoxBytes} to decrypt the result.
- *
- * @param data The data to encrypt.
- *
- * @param key The key to use for encryption.
- *
- * @returns The encrypted data and the generated nonce, both as base64 strings.
- *
- * [Note: 3 forms of encryption (Box | Blob | Stream)]
- *
- * libsodium provides two "high level" encryption patterns:
- *
- * 1. Authenticated encryption ("secretbox")
- * https://doc.libsodium.org/secret-key_cryptography/secretbox
- *
- * 2. Encrypted streams and file encryption ("secretstream")
- * https://doc.libsodium.org/secret-key_cryptography/secretstream
- *
- * In terms of the underlying algorithm, they are essentially the same.
- *
- * 1. The secretbox APIs use XSalsa20 with Poly1305 (where XSalsa20 is the
- * stream cipher used for encryption, which Poly1305 is the MAC used for
- * authentication).
- *
- * 2. The secretstream APIs use XChaCha20 with Poly1305.
- *
- * XSalsa20 is a minor variant (predecessor in fact) of XChaCha20. I am not
- * aware why libsodium uses both the variants, but they seem to have similar
- * characteristics.
- *
- * These two sets of APIs map functionally map to two different use cases.
- *
- * 1. If there is a single independent bit of data to encrypt, the secretbox
- * APIs fit the bill.
- *
- * 2. If there is a set of related data to encrypt, e.g. the contents of a file
- * where the file is too big to fit into a single message, then the
- * secretstream APIs are more appropriate.
- *
- * However, in our code we have evolved two different use cases for the 2nd
- * option. The data to encrypt might be smaller than our streaming encryption
- * chunk size (e.g. the public magic metadata associated with the
- * {@link EnteFile}), so we do not chunk it and instead encrypt / decrypt it in
- * a single go. In contrast, the actual file that the user wishes to upload may
- * be arbitrarily big, and there we first break in into chunks before using the
- * streaming encryption.
- *
- * Thus, we have three scenarios:
- *
- * 1. Box: Using secretbox APIs to encrypt some independent blob of data.
- *
- * 2. Blob: Using secretstream APIs without chunking. This is used to encrypt
- * data associated to an Ente object (file, collection, entity, etc), when
- * the data is small-ish (less than a few MBs).
- *
- * 3. Stream/Chunks: Using secretstream APIs for encrypting chunks. This is used
- * to encrypt the actual content of the files associated with an EnteFile
- * object. This itself happens in two ways:
- *
- * 3a. One shot mode - where we do break the data into chunks, but a single
- * function processes all the chunks in one go.
- *
- * 3b. Streaming - where all the chunks are processed one by one.
- *
- * "Blob" is not a prior term of art in this context, it is just something we
- * use to abbreviate "data encrypted using secretstream APIs without chunking".
- *
- * The distinction between Box and Blob is also handy since not only does the
- * underlying algorithm differ, but also the terminology that libsodium use for
- * the nonce.
- *
- * 1. When using the secretbox APIs, the nonce is called the "nonce", and needs
- * to be provided by us (the caller).
- *
- * 2. When using the secretstream APIs, the nonce is internally generated by
- * libsodium and provided by libsodium to us (the caller) as a "header".
- *
- * However, even for case 1, the functions we expose from libsodium.ts generate
- * the nonce for the caller. So for higher level functions, the difference
- * between Box and Blob encryption is:
- *
- * 1. Box uses secretbox APIs (Salsa), Blob uses secretstream APIs (ChaCha).
- *
- * 2. Blob should generally be used for data associated with an Ente object, and
- * Box for the other cases.
- *
- * 3. Box returns a "nonce", while Blob returns a "header".
- *
- * The difference between case 2 and 3 (Blob vs Stream) is that while both use
- * the same algorithms, in case of Blob the entire data is encrypted / decrypted
- * without chunking, whilst the *Stream routines first break it into
- * {@link streamEncryptionChunkSize} chunks.
- */
export const encryptBox = async (
data: BytesOrB64,
key: BytesOrB64,
@@ -281,21 +91,6 @@ export const encryptBox = async (
};
};
-/**
- * Encrypt the given data using libsodium's secretstream APIs without chunking.
- *
- * Use {@link decryptBlobBytes} to decrypt the result.
- *
- * @param data The data to encrypt.
- *
- * @param key The key to use for encryption.
- *
- * @returns The encrypted data and the decryption header as {@link Uint8Array}s.
- *
- * - See: [Note: 3 forms of encryption (Box | Blob | Stream)].
- *
- * - See: https://doc.libsodium.org/secret-key_cryptography/secretstream
- */
export const encryptBlobBytes = async (
data: BytesOrB64,
key: BytesOrB64,
@@ -319,12 +114,6 @@ export const encryptBlobBytes = async (
};
};
-/**
- * A higher level variant of {@link encryptBlobBytes} that returns the both the
- * encrypted data and decryption header as base64 strings.
- *
- * This is the variant expected to serve majority of the public API use cases.
- */
export const encryptBlob = async (
data: BytesOrB64,
key: BytesOrB64,
@@ -339,37 +128,12 @@ export const encryptBlob = async (
};
};
-/**
- * Encrypt the provided JSON value (using {@link encryptBlob}) after converting
- * it to a JSON string (and UTF-8 encoding it to obtain bytes).
- *
- * Use {@link decryptMetadataJSON} to decrypt the result and convert it back to
- * a JSON value.
- */
export const encryptMetadataJSON = (
jsonValue: unknown,
key: BytesOrB64,
): Promise<EncryptedBlobB64> =>
encryptBlob(new TextEncoder().encode(JSON.stringify(jsonValue)), key);
-/**
- * Encrypt the given data using libsodium's secretstream APIs after breaking it
- * into {@link streamEncryptionChunkSize} chunks.
- *
- * Use {@link decryptStreamBytes} to decrypt the result.
- *
- * Unlike {@link initChunkDecryption} / {@link encryptFileChunk}, this function
- * processes all the chunks at once in a single call to this function.
- *
- * @param data The data to encrypt.
- *
- * @returns The encrypted bytes ({@link Uint8Array}) and the decryption header
- * (as a base64 string).
- *
- * - See: [Note: 3 forms of encryption (Box | Blob | Stream)].
- *
- * - See: https://doc.libsodium.org/secret-key_cryptography/secretstream
- */
export const encryptStreamBytes = async (
data: Uint8Array,
key: BytesOrB64,
@@ -387,6 +151,7 @@ export const encryptStreamBytes = async (
while (tag !== sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL) {
let chunkSize = streamEncryptionChunkSize;
+ // Equality marks the last full-size chunk as final.
if (bytesRead + chunkSize >= data.length) {
chunkSize = data.length - bytesRead;
tag = sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL;
@@ -408,24 +173,6 @@ export const encryptStreamBytes = async (
};
};
-/**
- * Initialize libsodium's secretstream APIs for encrypting
- * {@link streamEncryptionChunkSize} chunks. Subsequently, each chunk can be
- * encrypted using {@link encryptStreamChunk}.
- *
- * Use {@link initChunkDecryption} to initialize the decryption routine, and
- * {@link decryptStreamChunk} to decrypt the individual chunks.
- *
- * See also: {@link encryptStreamBytes} which also does chunked encryption but
- * encrypts all the chunks in a single call.
- *
- * @param key The key to use for encryption.
- *
- * @returns The decryption header (as a base64 string) which should be preserved
- * and used during decryption, and an opaque "push state" that should be passed
- * to subsequent calls to {@link encryptStreamChunk} along with the chunks's
- * contents.
- */
export const initChunkEncryption = async (
key: BytesOrB64,
): Promise<InitChunkEncryptionResult> => {
@@ -436,24 +183,6 @@ export const initChunkEncryption = async (
return { decryptionHeader: await toB64(header), pushState: state };
};
-/**
- * Encrypt an individual chunk using libsodium's secretstream APIs.
- *
- * This function is not meant to be standalone, but is instead called in tandem
- * with {@link initChunkEncryption} for encrypting data after breaking it into
- * chunks.
- *
- * @param data The chunk's data as bytes ({@link Uint8Array}).
- *
- * @param pushState The state for this instantiation of chunked encryption. This
- * should be treated as opaque libsodium state that should be passed to all
- * calls to {@link encryptStreamChunk} that are paired with a particular
- * {@link initChunkEncryption}.
- *
- * @param isFinalChunk `true` if this is the last chunk in the sequence.
- *
- * @returns The encrypted chunk.
- */
export const encryptStreamChunk = async (
data: Uint8Array,
pushState: SodiumStateAddress,
@@ -473,9 +202,6 @@ export const encryptStreamChunk = async (
);
};
-/**
- * Decrypt the result of {@link encryptBox} and return the decrypted bytes.
- */
export const decryptBoxBytes = async (
{ encryptedData, nonce }: EncryptedBox,
key: BytesOrB64,
@@ -490,17 +216,11 @@ export const decryptBoxBytes = async (
);
};
-/**
- * Variant of {@link decryptBoxBytes} that returns the data as a base64 string.
- */
export const decryptBox = (
box: EncryptedBox,
key: BytesOrB64,
): Promise<string> => decryptBoxBytes(box, key).then(toB64);
-/**
- * Decrypt the result of {@link encryptBlobBytes} or {@link encryptBlob}.
- */
export const decryptBlobBytes = async (
{ encryptedData, decryptionHeader }: EncryptedBlob,
key: BytesOrB64,
@@ -518,23 +238,11 @@ export const decryptBlobBytes = async (
return ensureArrayBufferBacked(pullResult.message);
};
-/**
- * A variant of {@link decryptBlobBytes} that returns the result as a base64
- * string.
- */
export const decryptBlob = (
blob: EncryptedBlob,
key: BytesOrB64,
): Promise<string> => decryptBlobBytes(blob, key).then(toB64);
-/**
- * Decrypt the result of {@link encryptMetadataJSON} and return the JSON value
- * obtained by parsing the decrypted JSON string (which is obtained by UTF-8
- * decoding the decrypted bytes).
- *
- * Since TypeScript doesn't currently have a native JSON type, the returned
- * value is casted as an `unknown`.
- */
export const decryptMetadataJSON = async (
blob: EncryptedBlob,
key: BytesOrB64,
@@ -543,9 +251,6 @@ export const decryptMetadataJSON = async (
new TextDecoder().decode(await decryptBlobBytes(blob, key)),
) as unknown;
-/**
- * Decrypt the result of {@link encryptStreamBytes}.
- */
export const decryptStreamBytes = async (
{ encryptedData, decryptionHeader }: EncryptedFile,
key: BytesOrB64,
@@ -563,6 +268,7 @@ export const decryptStreamBytes = async (
let tag = sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE;
while (tag !== sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL) {
let chunkSize = decryptionChunkSize;
+ // Equality is still a complete encrypted chunk.
if (bytesRead + chunkSize > encryptedData.length) {
chunkSize = encryptedData.length - bytesRead;
}
@@ -578,20 +284,6 @@ export const decryptStreamBytes = async (
return mergeUint8Arrays(decryptedChunks);
};
-/**
- * Prepare to decrypt the result of {@link initChunkEncryption} and
- * {@link encryptStreamChunk}.
- *
- * @param decryptionHeader The header (as a base64 string) that was produced
- * during encryption by {@link initChunkEncryption}.
- *
- * @param key The encryption key.
- *
- * @returns The pull state, which should be treated as opaque libsodium specific
- * state that should be passed along to each subsequent call to
- * {@link decryptStreamChunk}, and the size of each (decrypted) chunk that will
- * be produced by subsequent calls to {@link decryptStreamChunk}.
- */
export const initChunkDecryption = async (
decryptionHeader: string,
key: BytesOrB64,
@@ -607,15 +299,6 @@ export const initChunkDecryption = async (
return { pullState, decryptionChunkSize };
};
-/**
- * Decrypt an individual chunk of the data encrypted using
- * {@link initChunkEncryption} and {@link encryptStreamChunk}.
- *
- * This is meant to be used in tandem with {@link initChunkDecryption}. During
- * each invocation, it should be passed the encrypted chunk, and the
- * {@link pullState} returned by {@link initChunkDecryption}. It will then
- * return the corresponding decrypted chunk's bytes.
- */
export const decryptStreamChunk = async (
data: Uint8Array,
pullState: SodiumStateAddress,
@@ -628,22 +311,6 @@ export const decryptStreamChunk = async (
return ensureArrayBufferBacked(pullResult.message);
};
-/**
- * Initialize and return new state that can be used to hash the chunks of data
- * in a streaming manner.
- *
- * [Note: Chunked hashing]
- *
- * 1. Obtain a hash state using {@link chunkHashInit}.
- *
- * 2. Pass the hash state and the data chunk to {@link chunkHashUpdate}.
- *
- * 3. Finalize the hash state and obtain the hash using {@link chunkHashFinal}.
- *
- * @returns An opaque object representing the hash state. This can be passed
- * (along with the data to hash) to {@link chunkHashUpdate}, and the final hash
- * obtained using {@link chunkHashFinal}.
- */
export const chunkHashInit = async (): Promise<SodiumStateAddress> => {
await sodium.ready;
return sodium.crypto_generichash_init(
@@ -652,15 +319,6 @@ export const chunkHashInit = async (): Promise<SodiumStateAddress> => {
);
};
-/**
- * Update the hash state to incorporate the contents of the provided data chunk.
- *
- * See: [Note: Chunked hashing]
- *
- * @param hashState A hash state obtained using {@link chunkHashInit}.
- *
- * @param chunk The data (bytes) to hash.
- */
export const chunkHashUpdate = async (
hashState: SodiumStateAddress,
chunk: Uint8Array,
@@ -669,16 +327,6 @@ export const chunkHashUpdate = async (
sodium.crypto_generichash_update(hashState, chunk);
};
-/**
- * Finalize a hash state and return the hash it represents (as a base64 string).
- *
- * See: [Note: Chunked hashing]
- *
- * @param hashState A hash state obtained using {@link chunkHashInit} and fed
- * chunks using {@link chunkHashUpdate}.
- *
- * @returns The hash of all the chunks (as a base64 string).
- */
export const chunkHashFinal = async (hashState: SodiumStateAddress) => {
await sodium.ready;
const hash = sodium.crypto_generichash_final(
@@ -688,13 +336,6 @@ export const chunkHashFinal = async (hashState: SodiumStateAddress) => {
return toB64(hash);
};
-/**
- * Generate a new public/private keypair for use with public-key encryption
- * functions, and return their base64 string representations.
- *
- * These keys are suitable for being used with the {@link boxSeal} and
- * {@link boxSealOpen} functions.
- */
export const generateKeyPair = async () => {
await sodium.ready;
const keyPair = sodium.crypto_box_keypair();
@@ -704,20 +345,6 @@ export const generateKeyPair = async () => {
};
};
-/**
- * Public key encryption.
- *
- * Encrypt the given {@link data} using the given {@link publicKey}.
- *
- * This function performs asymmetric (public-key) encryption. To decrypt the
- * result, use {@link boxSealOpen}.
- *
- * @param data The input data to encrypt, represented as a base64 string.
- *
- * @param publicKey The public key to use for encryption (as a base64 string).
- *
- * @returns The encrypted data (as a base64 string).
- */
export const boxSeal = async (data: string, publicKey: string) => {
await sodium.ready;
return toB64(
@@ -725,12 +352,6 @@ export const boxSeal = async (data: string, publicKey: string) => {
);
};
-/**
- * Decrypt the result of {@link boxSeal}.
- *
- * All parameters are base64 string representations of the underlying data. The
- * result is the bytes obtained by decryption.
- */
export const boxSealOpenBytes = async (
encryptedData: string,
{ publicKey, privateKey }: KeyPair,
@@ -745,45 +366,14 @@ export const boxSealOpenBytes = async (
);
};
-/**
- * A variant of {@link boxSealOpenBytes} that returns the result as a base64
- * string.
- */
export const boxSealOpen = async (encryptedData: string, keyPair: KeyPair) =>
toB64(await boxSealOpenBytes(encryptedData, keyPair));
-/**
- * Generate a new randomly generated 128-bit salt suitable for use with the key
- * derivation functions ({@link deriveKey} and its variants).
- *
- * @returns The base64 representation of a randomly generated 128-bit salt.
- */
export const generateDeriveKeySalt = async () => {
await sodium.ready;
return await toB64(sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES));
};
-/**
- * Derive a key by hashing the given {@link passphrase} using Argon 2id.
- *
- * While the underlying primitive is a password hash (e.g for its storage), this
- * function is also meant for key derivation using a low-entropy input by
- * deriving a longer hash from the user's human chosen passphrase.
- *
- * The returned key can be used with the various *Box encryption routines.
- *
- * @param passphrase The password / passphrase to hash (normal UTF-8 string).
- *
- * @param salt Base64 string representing the salt to use when hashing.
- *
- * @param opsLimit Operation limit. The maximum amount of computations to
- * perform.
- *
- * @param memLimit Memory limit. The maximum amount of RAM to use.
- *
- * @returns The base64 representation of a 256-bit key suitable for being used
- * with libsodium's secretbox APIs.
- */
export const deriveKey = async (
passphrase: string,
salt: string,
@@ -803,18 +393,6 @@ export const deriveKey = async (
);
};
-/**
- * A variant of {@link deriveKey} with (dynamic) parameters for deriving
- * sensitive keys (like the user's master key KEK (key encryption key).
- *
- * This function defers to {@link deriveKey} after choosing the most secure ops
- * and mem limits that the current device can handle. For details about these
- * limits, see https://libsodium.gitbook.io/doc/password_hashing/default_phf.
- *
- * @returns Both the derived key, and the ops and mem limits that were chosen
- * during the derivation (this information will be needed the user's other
- * clients to derive the same result).
- */
export const deriveSensitiveKey = async (
passphrase: string,
): Promise<DerivedKey> => {
@@ -825,29 +403,19 @@ export const deriveSensitiveKey = async (
const desiredStrength =
sodium.crypto_pwhash_MEMLIMIT_SENSITIVE *
sodium.crypto_pwhash_OPSLIMIT_SENSITIVE;
- // When the sensitive memLimit (1 GB) is used, on low spec devices the OS
- // often kills the app with OOM. Note that could happen at a later stage
- // too, so checking the current device's capabilities will not help. For
- // example, the user may create an account on a powerful desktop device, but
- // then try to log in later on their weaker mobile device, and will need to
- // reset their password.
- //
- // To avoid this, we start with the moderate memLimit (256 MB), but scale up
- // the opsLimit correspondingly (16). This ensures that the product of these
- // two variables (the area under the graph that determines the amount of
- // work) stays the same.
- let memLimit = sodium.crypto_pwhash_MEMLIMIT_MODERATE; // = 256 MB
+ // A 1 GiB memory cost can make weaker devices OOM after an account was
+ // created elsewhere. Preserve the same work factor with less memory.
+ let memLimit = sodium.crypto_pwhash_MEMLIMIT_MODERATE;
const factor = Math.floor(
sodium.crypto_pwhash_MEMLIMIT_SENSITIVE /
sodium.crypto_pwhash_MEMLIMIT_MODERATE,
- ); // = 4
- let opsLimit = sodium.crypto_pwhash_OPSLIMIT_SENSITIVE * factor; // = 16
+ );
+ let opsLimit = sodium.crypto_pwhash_OPSLIMIT_SENSITIVE * factor;
if (memLimit * opsLimit != desiredStrength) {
throw new Error(`Invalid mem and ops limits: ${memLimit}, ${opsLimit}`);
}
- // Keep the adaptive floor aligned with the server-side minimum accepted
- // account KDF memory limit (128 MiB), not libsodium's absolute minimum.
+ // Museum rejects account KDFs below 128 MiB.
const minMemLimit = 128 * 1024 * 1024;
while (memLimit >= minMemLimit) {
try {
@@ -861,10 +429,6 @@ export const deriveSensitiveKey = async (
throw new Error(deriveKeyInsufficientMemoryErrorMessage);
};
-/**
- * A variant of {@link deriveSensitiveKey} for deriving an alternative key with
- * parameters suitable for interactive use.
- */
export const deriveInteractiveKey = async (
passphrase: string,
): Promise<DerivedKey> => {
@@ -876,10 +440,6 @@ export const deriveInteractiveKey = async (
return { key, salt, opsLimit, memLimit };
};
-/**
- * A variant of {@link deriveSensitiveKey} for deriving an alternative key with
- * parameters suitable for moderate-cost password gates.
- */
export const deriveModerateKey = async (
passphrase: string,
): Promise<DerivedKey> => {
@@ -891,34 +451,6 @@ export const deriveModerateKey = async (
return { key, salt, opsLimit, memLimit };
};
-/**
- * Derive a {@link subKeyID}-th subkey of length {@link subKeyLength} bytes by
- * applying a KDF (Key Derivation Function) for the given {@link key} and the
- * {@link context}.
- *
- * Multiple secret subkeys can be (deterministically) derived from a single
- * high-entropy key. Knowledge of the derived key does not impact the security
- * of the key from which it was derived, or of its potential sibling subkeys.
- *
- * See: https://doc.libsodium.org/key_derivation
- *
- * @param key The key whose subkey we are deriving. In the context of
- * key derivation, this is usually referred to as the "master key", but we
- * deemphasize that nomenclature to avoid confusion with the user's master key.
- *
- * @param subKeyLength The length of the required subkey.
- *
- * @param subKeyID An identifier of the subkey.
- *
- * @param context A short but otherwise arbitrary string (non-secret) used to
- * separate domains in which the subkeys are going to be used.
- *
- * @returns The bytes of the subkey.
- *
- * Note that returning bytes is a bit unusual, usually we'd return the base64
- * string from functions. However, this particular function is used in only one
- * place in our code, and so we adapt the interface for its convenience.
- */
export const deriveSubKeyBytes = async (
key: BytesOrB64,
subKeyLength: number,
diff --git a/web/packages/base/crypto/types.ts b/web/packages/base/crypto/types.ts
index 049fe45a47..3181dc01bb 100644
--- a/web/packages/base/crypto/types.ts
+++ b/web/packages/base/crypto/types.ts
@@ -1,243 +1,63 @@
-/**
- * @file types shared between the public API (main thread) and implementation
- * (worker thread). Also some constants, but no code.
- */
import type { StateAddress } from "libsodium-wrappers-sumo";
-/**
- * An opaque object meant to be threaded through various functions that deal
- * with resumable chunk based processing.
- */
export type SodiumStateAddress = StateAddress;
-/**
- * The various *Stream encryption functions break up the input into chunks of
- * {@link streamEncryptionChunkSize} bytes during encryption (except the last
- * chunk which can be smaller since a file would rarely align exactly to a
- * {@link streamEncryptionChunkSize} multiple).
- *
- * The various *Stream decryption functions also assume that each potential
- * chunk is {@link streamEncryptionChunkSize} long.
- *
- * This value of this constant is 4 MB (and is unlikely to change).
- */
+// Existing encrypted files depend on this chunk boundary.
export const streamEncryptionChunkSize = 4 * 1024 * 1024;
-/**
- * The message of the {@link Error} that is thrown by {@link deriveSensitiveKey}
- * if we could not find acceptable ops and mem limit combinations without
- * exceeded the maximum mem limit.
- *
- * Generally, this indicates that the current device is not powerful enough to
- * perform the key derivation. This is rare for computers, but can happen with
- * older mobile devices with too little RAM.
- */
export const deriveKeyInsufficientMemoryErrorMessage =
"Failed to derive key (insufficient memory)";
-/**
- * Data provided either as bytes ({@link Uint8Array}) or their base64 string
- * representation.
- */
export type BytesOrB64 = Uint8Array | string;
-/**
- * The result of encryption using the secretbox APIs.
- *
- * It contains an encrypted data and a randomly generated nonce that was used
- * during encryption. Both these values are needed to decrypt the data. The
- * nonce does not need to be secret.
- *
- * See: [Note: 3 forms of encryption (Box | Blob | Stream)].
- */
export interface EncryptedBox {
- /**
- * The data to decrypt.
- */
encryptedData: BytesOrB64;
- /**
- * The nonce that was used during encryption.
- *
- * The nonce is required to decrypt the data, but it does not need to be
- * kept secret.
- */
nonce: BytesOrB64;
}
export interface EncryptedBoxB64 {
- /**
- * The encrypted data as a base64 string.
- */
encryptedData: string;
- /**
- * The nonce that was used during encryption, as a base64 string.
- *
- * The nonce is required to decrypt the data, but it does not need to be
- * kept secret.
- */
nonce: string;
}
-/**
- * The result of encryption using the secretstream APIs without chunking.
- *
- * It contains an encrypted data and a header that should be provided during
- * decryption. The header does not need to be secret.
- *
- * See: [Note: 3 forms of encryption (Box | Blob | Stream)].
- *
- * This type is a combination of {@link EncryptedBlobBytes} and
- * {@link EncryptedBlobB64} which allows the decryption routines to accept
- * either the bytes or the base64 variants produced by the encryption routines.
- */
export interface EncryptedBlob {
- /**
- * The encrypted data.
- */
encryptedData: BytesOrB64;
- /**
- * The decryption header.
- *
- * While the exact contents of the header are libsodium's internal details,
- * it effectively contains a random nonce generated by libsodium. It does
- * not need to be secret, but it is required to decrypt the data.
- */
decryptionHeader: BytesOrB64;
}
-/**
- * A variant of {@link EncryptedBlob} that has the encrypted data and header
- * as bytes ({@link Uint8Array}s).
- */
export interface EncryptedBlobBytes {
- /**
- * The encrypted data.
- */
encryptedData: Uint8Array<ArrayBuffer>;
- /**
- * The decryption header.
- *
- * While the exact contents of the header are libsodium's internal details,
- * it effectively contains a random nonce generated by libsodium. It does
- * not need to be secret, but it is required to decrypt the data.
- */
decryptionHeader: Uint8Array<ArrayBuffer>;
}
-/**
- * A variant of {@link EncryptedBlob} that has the encrypted data and header
- * as base64 strings.
- */
export interface EncryptedBlobB64 {
- /**
- * The encrypted data as a base64 string.
- */
encryptedData: string;
- /**
- * A base64 string containing the decryption header.
- *
- * While the exact contents of the header are libsodium's internal details,
- * it effectively contains a random nonce generated by libsodium. It does
- * not need to be secret, but it is required to decrypt the data.
- */
decryptionHeader: string;
}
-/**
- * An intermediate between {@link EncryptedBlobBytes} and
- * {@link EncryptedBlobB64} that has the encrypted as bytes
- * ({@link Uint8Array}s), but the {@link decryptionHeader} as a base64 string.
- *
- * Such a format is handy for encrypting files, since it can then directly be
- * used (the file's encrypted bytes get uploaded separately, whilst the base64
- * decryption header becomes part of the corresponding {@link EnteFile}).
- */
export interface EncryptedFile {
- /**
- * The encrypted data.
- */
encryptedData: Uint8Array<ArrayBuffer>;
- /**
- * A base64 string containing the decryption header.
- *
- * While the exact contents of the header are libsodium's internal details,
- * it effectively contains a random nonce generated by libsodium. It does
- * not need to be secret, but it is required to decrypt the data.
- */
decryptionHeader: string;
}
-/**
- * An object returned by the init function of chunked encryption routines.
- */
export interface InitChunkEncryptionResult {
- /**
- * A base64 string containing the decryption header.
- *
- * While the exact contents of the header are libsodium's internal details,
- * it effectively contains a random nonce generated by libsodium. It does
- * not need to be secret, but it is required to decrypt the data.
- */
decryptionHeader: string;
- /**
- * An opaque value that refers to the internal state used by the resumable
- * calls in the encryption sequence.
- */
pushState: SodiumStateAddress;
}
-/**
- * An object returned by the init function of chunked decryption routines.
- */
export interface InitChunkDecryptionResult {
- /**
- * An opaque value that refers to the internal state used by the resumable
- * calls in the decryption sequence.
- */
pullState: SodiumStateAddress;
- /**
- * The expected size of each chunk.
- */
decryptionChunkSize: number;
}
-/**
- * A pair of public and private keys.
- */
export interface KeyPair {
- /**
- * The public key of the keypair, as a base64 encoded string.
- */
publicKey: string;
- /**
- * The private key of the keypair, as a base64 encoded string.
- *
- * Some places also refer to it as the "secret key".
- *
- * See: [Note: privateKey and secretKey].
- */
privateKey: string;
}
-/**
- * A key derived from a user provided passphrase, and the various attributes
- * that were used during the key derivation.
- */
export interface DerivedKey {
- /**
- * The newly derived key itself, as a base64 encoded string.
- */
key: string;
- /**
- * The randomly generated salt (as a base64 string) that was used when deriving the key.
- */
salt: string;
- /**
- * opsLimit used during key derivation.
- */
opsLimit: number;
- /**
- * memLimit used during key derivation.
- * */
memLimit: number;
}
diff --git a/web/packages/base/http.ts b/web/packages/base/http.ts
index 7dfcf6111b..c5368dabd5 100644
--- a/web/packages/base/http.ts
+++ b/web/packages/base/http.ts
@@ -5,70 +5,20 @@ import { clientPackageName } from "./app";
import log from "./log";
import { ensureAuthToken } from "./token";
-/**
- * Return headers that should be passed alongwith (almost) all authenticated
- * `fetch` calls that we make to our API servers.
- *
- * - The auth token
- * - The client package name.
- */
export const authenticatedRequestHeaders = async () => ({
"X-Auth-Token": await ensureAuthToken(),
"X-Client-Package": clientPackageName,
...(isDesktop && { "X-Client-Version": desktopAppVersion }),
});
-/**
- * Return headers that should be passed alongwith (almost) all unauthenticated
- * `fetch` calls that we make to our remotes like our API servers (museum), or
- * to pre-signed URLs that are handled by the S3 storage buckets themselves.
- *
- * - The client package name.
- */
export const publicRequestHeaders = () => ({
"X-Client-Package": clientPackageName,
...(isDesktop && { "X-Client-Version": desktopAppVersion }),
});
-/**
- * A set of credentials needed to make public collections related API requests.
- */
export interface PublicAlbumsCredentials {
- /**
- * [Note: Public album access token]
- *
- * The public album access is a token that serves a similar purpose as the
- * "X-Auth-Token" for usual authenticated API requests that happen for a
- * logged in user, except:
- *
- * - It will be passed as the "X-Auth-Access-Token" header, and
- * - It also tells remote about the public album under consideration.
- *
- * This access token is variously referred to as the album token, or the
- * auth token, when the context is clear. The client obtains this from the
- * "t" query parameter of a public album URL, and then uses it both to:
- *
- * 1. Identify and authenticate itself with remote (this header).
- *
- * 2. Scope local storage per public album by using this access token as a
- * part of the local storage key. In this context it is sometimes also
- * referred to as a "collectionUID" by old code.
- */
accessToken: string;
- /**
- * [Note: Password token for public albums requests].
- *
- * A password protected access token. This is only needed for albums that
- * are behind a password. In such cases, the client needs to fetch this
- * extra token from remote (in exchange for the public album's password),
- * and then pass it as the "X-Auth-Access-Token-JWT" header in authenticated
- * public collections related API requests.
- */
accessTokenJWT?: string | undefined;
- /**
- * A signed token issued after this browser has been admitted once for this
- * public link's device limit. It is separate from the password JWT.
- */
linkDeviceToken?: string | undefined;
}
@@ -79,14 +29,6 @@ export const linkDeviceTokenResponseHeader = "X-Ente-Link-Device-Token";
export const linkDeviceTokenFromResponse = (res: Response) =>
res.headers.get(linkDeviceTokenResponseHeader) ?? undefined;
-/**
- * Return headers that should be passed alongwith public collection related
- * authenticated `fetch` calls that we make to our API servers.
- *
- * - The auth token.
- * - The password protected auth token (if provided).
- * - The client package name.
- */
export const authenticatedPublicAlbumsRequestHeaders = ({
accessToken,
accessTokenJWT,
@@ -108,19 +50,12 @@ export const authenticatedPublicAlbumsDeviceLimitRequestHeaders = (
export const authenticatedPublicAlbumsInfoRequestHeaders =
authenticatedPublicAlbumsDeviceLimitRequestHeaders;
-/**
- * A custom Error that is thrown if a fetch fails with a non-2xx HTTP status.
- */
export class HTTPError extends Error {
res: Response;
details: Record<string, string>;
constructor(res: Response) {
- // Trim off any query parameters from the URL before logging, it may
- // have tokens.
- //
- // Nb: res.url is URL obtained after any redirects, and thus is not
- // necessarily the same as the request's URL.
+ // Query parameters can contain auth tokens; never put them in logs.
const url = new URL(res.url);
url.search = "";
super(`HTTP ${res.status} ${res.statusText} (${url.pathname})`);
@@ -128,8 +63,6 @@ export class HTTPError extends Error {
const requestID = res.headers.get("x-request-id");
const details = { url: url.href, ...(requestID && { requestID }) };
- // Cargo culted from
- // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
Error.captureStackTrace?.(this, HTTPError);
this.name = this.constructor.name;
@@ -138,10 +71,6 @@ export class HTTPError extends Error {
}
}
-/**
- * A convenience method that throws an {@link HTTPError} if the given
- * {@link Response} does not have a HTTP 2xx status.
- */
export const ensureOk = (res: Response) => {
if (!res.ok) {
const e = new HTTPError(res);
@@ -150,45 +79,15 @@ export const ensureOk = (res: Response) => {
}
};
-/**
- * Return true if this is a HTTP error with the given {@link httpStatus}.
- */
export const isHTTPErrorWithStatus = (e: unknown, httpStatus: number) =>
e instanceof HTTPError && e.res.status == httpStatus;
-/**
- * Return true if this is a HTTP "client" error.
- *
- * This is a convenience matcher to check if {@link e} is an instance of
- * {@link HTTPError} with a 4xx status code. Such errors are client errors, and
- * (generally) retrying them will not help.
- */
export const isHTTP4xxError = (e: unknown) =>
e instanceof HTTPError && e.res.status >= 400 && e.res.status <= 499;
-/**
- * Return true if this is a HTTP 401 error.
- *
- * For authenticated requests, an HTTP "401 Unauthorized" indicates that the
- * credentials (auth token) is not valid.
- */
export const isHTTP401Error = (e: unknown) =>
e instanceof HTTPError && e.res.status == 401;
-/**
- * Return `true` if this is an error because of a HTTP failure response returned
- * by museum with the given "code" and HTTP status.
- *
- * > The function is async because it needs to parse the payload.
- *
- * For some known set of errors, museum returns a payload of the form
- *
- * {"code":"USER_NOT_REGISTERED","message":"User is not registered"}
- *
- * where the code can be used to match a specific reason for the HTTP request
- * failing. This function can be used as a predicate to check both the HTTP
- * status code and the "code" within the payload.
- */
export const isMuseumHTTPError = async (
e: unknown,
httpStatus: number,
@@ -209,51 +108,11 @@ export const isMuseumHTTPError = async (
};
interface RetryAsyncOperationOpts {
- /**
- * An optional modification to the default wait times between retries.
- *
- * - default 1 orig + 3 retries (2s, 5s, 10s)
- * - "background" 1 orig + 3 retries (5s, 25s, 120s)
- *
- * default is fine for most operations, including interactive ones where we
- * don't want to wait too long before giving up. "background" is suitable
- * for non-interactive operations where we can wait for longer (thus better
- * handle remote hiccups) without degrading the user's experience.
- */
retryProfile?: "background";
- /**
- * An optional function that is called with the corresponding error whenever
- * {@link op} rejects. It should throw the error if the retries should
- * immediately be aborted.
- */
abortIfNeeded?: (error: unknown) => void;
}
-/**
- * Retry a async operation on failure up to 4 times (1 original + 3 retries)
- * with exponential backoff.
- *
- * [Note: Retries of network requests should be idempotent]
- *
- * When dealing with network requests, avoid using this function directly, use
- * one of its wrappers like {@link retryEnsuringHTTPOk} instead. Those wrappers
- * ultimately use this function only, and there is nothing wrong with this
- * function generally, however since this function allows retrying arbitrary
- * promises, it is easy accidentally try and attempt retries of non-idemponent
- * requests, while the more restricted API of {@link retryEnsuringHTTPOk} and
- * other {@link HTTPRequestRetrier}s makes such misuse less likely.
- *
- * @param op A function that performs the operation, returning the promise for
- * its completion.
- *
- * @param opts Optional tweaks to the default implementation. See
- * {@link RetryAsyncOperationOpts}.
- *
- * @returns A promise that fulfills with to the result of a first successfully
- * fulfilled promise of the 4 (1 + 3) attempts, or rejects with the error
- * obtained either when {@link abortIfNeeded} throws, or with the error from the
- * last attempt otherwise.
- */
+// Only retry operations whose repeated execution is safe.
export const retryAsyncOperation = async <T>(
op: () => Promise<T>,
opts?: RetryAsyncOperationOpts,
@@ -279,15 +138,6 @@ export const retryAsyncOperation = async <T>(
}
};
-/**
- * A function that wraps the request(s) in retries if needed.
- *
- * See {@link retryEnsuringHTTPOk} for the canonical example. This typedef is to
- * allow us to talk about and pass functions that behave similar to
- * {@link retryEnsuringHTTPOk}, but perhaps with other additional checks.
- *
- * See also: [Note: Retries of network requests should be idempotent]
- */
export type HTTPRequestRetrier = (
request: () => Promise<Response>,
opts?: HTTPRequestRetrierOpts,
@@ -295,12 +145,6 @@ export type HTTPRequestRetrier = (
type HTTPRequestRetrierOpts = Pick<RetryAsyncOperationOpts, "retryProfile">;
-/**
- * A helper function to adapt {@link retryAsyncOperation} for HTTP fetches.
- *
- * This extends {@link retryAsyncOperation} by treating any non-200 OK status
- * (as matched by {@link ensureOk}) as an error that should be retried.
- */
export const retryEnsuringHTTPOk: HTTPRequestRetrier = (
request: () => Promise<Response>,
opts?: HTTPRequestRetrierOpts,
@@ -311,13 +155,6 @@ export const retryEnsuringHTTPOk: HTTPRequestRetrier = (
return r;
}, opts);
-/**
- * A helper function to adapt {@link retryAsyncOperation} for HTTP fetches, but
- * treating any 4xx HTTP responses as irrecoverable failures.
- *
- * This is similar to {@link retryEnsuringHTTPOk}, except it stops retrying if
- * remote responds with a 4xx HTTP status.
- */
export const retryEnsuringHTTPOkOr4xx: HTTPRequestRetrier = (
request: () => Promise<Response>,
opts?: HTTPRequestRetrierOpts,
diff --git a/web/packages/base/session.ts b/web/packages/base/session.ts
index f93b4f9c7e..ccb7cfa83c 100644
--- a/web/packages/base/session.ts
+++ b/web/packages/base/session.ts
@@ -2,21 +2,8 @@ import { z } from "zod";
import { decryptBox, encryptBox, generateKey } from "./crypto";
import log from "./log";
-/**
- * Remove all data stored in session storage (data tied to the browser tab).
- *
- * See `docs/storage.md` for more details about session storage. Currently, only
- * the following entries are stored in session storage:
- *
- * - "encryptionKey"
- * - "keyEncryptionKey" (transient)
- */
export const clearSessionStorage = () => sessionStorage.clear();
-/**
- * Schema of JSON string value for the "encryptionKey" and "keyEncryptionKey"
- * keys strings stored in session storage.
- */
const SessionKeyData = z.object({
encryptedData: z.string(),
key: z.string(),
@@ -31,34 +18,15 @@ const sessionKeyData = async (keyData: string): Promise<SessionKeyData> => {
return { key, ...box };
};
-/**
- * Return the user's decrypted master key (as a base64 string) from session
- * storage, or throw if the session storage does not have the master key (which
- * likely indicates that the user is not logged in).
- */
export const ensureMasterKeyFromSession = async () => {
const key = await masterKeyFromSession();
if (!key) throw new Error("Master key not found in session");
return key;
};
-/**
- * Return `true` if the user's encrypted master key is present in the session.
- *
- * Use {@link masterKeyFromSession} to get the actual master key after
- * decrypting it. This function is a similar but quicker check to verify if we
- * have credentials at hand or not, however it doesn't attempt to verify that
- * the key present in the session can actually be decrypted.
- */
export const haveMasterKeyInSession = () =>
!!sessionStorage.getItem("encryptionKey");
-/**
- * Return the decrypted user's master key (as a base64 string) from session
- * storage if they are logged in, otherwise return `undefined`.
- *
- * See also {@link ensureMasterKeyFromSession}, which is usually what we need.
- */
export const masterKeyFromSession = async () => {
const value = sessionStorage.getItem("encryptionKey");
if (!value) return undefined;
@@ -69,39 +37,16 @@ export const masterKeyFromSession = async () => {
return decryptBox({ encryptedData, nonce }, key);
};
-/**
- * Save the user's encrypted master key in the session storage. If we're running
- * in the context of our desktop app, also save it in the OS safe storage.
- *
- * See: [Note: Safe storage and interactive KEK attributes]
- *
- * @param masterKey The user's master key (as a base64 encoded string).
- */
+// Desktop safe storage is optional; failures fall back to password entry next session.
export const saveMasterKeyInSessionAndSafeStore = async (masterKey: string) => {
await saveKeyInSessionStore("encryptionKey", masterKey);
try {
await globalThis.electron?.saveMasterKeyInSafeStorage(masterKey);
} catch (e) {
- // [Note: Safe storage is best effort]
- //
- // The user might be running on an OS which does not provide secure
- // storage. Practically this is rare, but it can happen, especially on
- // Linux if the app is run in a desktop environment without libsecret.
- //
- // So intercept failures to read and write to safe storage, and
- // gracefully degrade to how the web app behaves (ask the user for their
- // password in each session).
log.warn("Failed to save master key in safe storage", e);
}
};
-/**
- * Save the provided key in session storage.
- *
- * @param keyName The name of the key use for the session storage entry.
- *
- * @param keyData The base64 encoded bytes of the key.
- */
const saveKeyInSessionStore = async (keyName: string, keyData: string) => {
sessionStorage.setItem(
keyName,
@@ -109,32 +54,6 @@ const saveKeyInSessionStore = async (keyName: string, keyData: string) => {
);
};
-/**
- * If we're running in the context of the desktop app, then read the master key
- * from the OS safe storage and put it into the session storage (if it is not
- * already present there).
- *
- * [Note: Safe storage and interactive KEK attributes]
- *
- * In the electron app we have the option of using the OS's safe storage (if
- * available) to store the master key so that the user does not have to reenter
- * their password each time they open the app.
- *
- * Such an ability is not present on browsers currently, so we need to ask the
- * user for their password to derive the KEK for decrypting their master key
- * each time they open the app in a new time (See: [Note: Key encryption key]).
- *
- * However, the default KEK parameters are not suitable for such frequent
- * interactive usage. So for the user's convenience, we also derive an new (so
- * called "intermediate") KEK using parameters suitable for interactive usage.
- * This KEK is not saved to remote, it is only maintained locally.
- *
- * In either case, eventually we want the encrypted key to be available in the
- * session for decrypting the user's files etc. In the web case, the page where
- * the user reenters their password will put it there, while on desktop
- * (assuming the key has already been saved to the OS safe storage), this
- * {@link updateSessionFromElectronSafeStorageIfNeeded} function will do it.
- */
export const updateSessionFromElectronSafeStorageIfNeeded = async () => {
const electron = globalThis.electron;
if (!electron) return;
@@ -145,7 +64,6 @@ export const updateSessionFromElectronSafeStorageIfNeeded = async () => {
try {
masterKey = await electron.masterKeyFromSafeStorage();
} catch (e) {
- // See: [Note: Safe storage is best effort]
log.warn("Failed to read master key from safe storage", e);
}
if (masterKey) {
@@ -153,41 +71,15 @@ export const updateSessionFromElectronSafeStorageIfNeeded = async () => {
}
};
-/**
- * Save the user's encypted key encryption key ("key") in session store
- * temporarily, until we get back here after completing the second factor.
- *
- * See: [Note: Stashing KEK in session store]
- *
- * @param kek The user's key encryption key (as a base64 string).
- */
+// Session storage carries the KEK across the 2FA app redirect.
export const stashKeyEncryptionKeyInSessionStore = (kek: string) =>
saveKeyInSessionStore("keyEncryptionKey", kek);
-/**
- * Return the decrypted user's key encryption key ("KEK") from session storage
- * if present, otherwise return `undefined`.
- *
- * The key (if it was present) is also removed from session storage.
- *
- * @returns the previously stashed key (if any) as a base64 string.
- *
- * [Note: Stashing KEK in session store]
- *
- * During login, if the user has set a second factor (passkey or TOTP), then we
- * need to redirect them to the accounts app or TOTP page to verify the second
- * factor. This second factor verification happens after password verification,
- * but simply storing the decrypted KEK in-memory wouldn't work because the
- * second factor redirect can happen to a separate accounts app altogether.
- *
- * So instead, we stash the encrypted KEK in session store (using
- * {@link stashKeyEncryptionKeyInSessionStore}), and after redirect, retrieve it
- * (after clearing it) using {@link unstashKeyEncryptionKeyFromSession}.
- */
export const unstashKeyEncryptionKeyFromSession = async () => {
const value = sessionStorage.getItem("keyEncryptionKey");
if (!value) return undefined;
+ // Consume the stashed KEK once.
sessionStorage.removeItem("keyEncryptionKey");
const { encryptedData, key, nonce } = SessionKeyData.parse(
diff --git a/web/packages/base/types/ipc.ts b/web/packages/base/types/ipc.ts
index f707409f2d..8881e65a93 100644
--- a/web/packages/base/types/ipc.ts
+++ b/web/packages/base/types/ipc.ts
@@ -1,997 +1,203 @@
-// Following are types shared with the Electron process. This list is manually
-// kept in sync with `desktop/src/types/ipc.ts`.
-//
-// See [Note: types.ts <-> preload.ts <-> ipc.ts]
-
-/**
- * Native provider used for desktop app lock authentication.
- *
- * `touchid` means we can use the platform-native auth prompt.
- * `none` means no supported native provider is currently available.
- */
+// Keep this bridge in sync with desktop/src/types/ipc.ts and desktop/src/preload.ts.
export type NativeDeviceLockProvider = "touchid" | "none";
-/**
- * Why native device lock is unavailable on this machine/session.
- */
export type NativeDeviceLockUnavailableReason =
| "unsupported-platform"
| "touchid-not-enrolled"
| "touchid-temporarily-unavailable"
| "touchid-api-error";
-/**
- * Capability metadata used by the renderer to decide whether to show and use
- * "Device lock" as an app-lock mode.
- */
export interface NativeDeviceLockCapability {
- /** True when native auth can be prompted right now. */
available: boolean;
- /** Which native provider backs authentication (if available). */
provider: NativeDeviceLockProvider;
- /** Present when unavailable, with a machine-readable reason. */
reason?: NativeDeviceLockUnavailableReason;
}
-/**
- * Persisted desktop app-lock configuration.
- *
- * This excludes the passphrase hash material, which continues to live in the
- * renderer KV DB.
- */
export interface PersistedAppLockConfig {
enabled: boolean;
lockType: "pin" | "password" | "device" | "none";
autoLockTimeMs: number;
}
-/**
- * Extra APIs provided by our Node.js layer when our code is running inside our
- * desktop (Electron) app.
- *
- * This list is manually kept in sync with `desktop/src/preload.ts`. In case of
- * a mismatch, the types may lie. See also: [Note: types.ts <-> preload.ts <->
- * ipc.ts]
- *
- * These extra objects and functions will only be available when our code is
- * running as the renderer process in Electron. These can be accessed by using
- * the `electron` property of the window (See @{link globalElectron} for a
- * systematic way of getting at that).
- */
export interface Electron {
- // - General
-
- /**
- * Return the version of the desktop app.
- *
- * The return value is of the form `v1.2.3`.
- */
appVersion: () => Promise<string>;
-
- /**
- * Log the given {@link message} to the on-disk log file maintained by the
- * desktop app.
- *
- * Note: Unlike the other functions exposed over the Electron bridge,
- * logToDisk is fire-and-forget and does not return a promise.
- */
logToDisk: (message: string) => void;
-
- /**
- * Open the given {@link dirPath} in the system's folder viewer.
- *
- * For example, on macOS this'll open {@link dirPath} in Finder.
- */
openDirectory: (dirPath: string) => Promise<void>;
-
- /**
- * Open the app's log directory in the system's folder viewer.
- *
- * @see {@link openDirectory}
- */
openLogDirectory: () => Promise<void>;
-
- /**
- * Ask the user to select a directory on their local file system, and return
- * it path.
- *
- * The returned path is guaranteed to use POSIX separators ('/').
- *
- * We don't strictly need IPC for this, we can use a hidden <input> element
- * and trigger its click for the same behaviour (as we do for the
- * `useFileInput` hook that we use for uploads). However, it's a bit
- * cumbersome, and we anyways will need to IPC to get back its full path, so
- * it is just convenient to expose this direct method.
- */
selectDirectory: () => Promise<string | undefined>;
-
- /**
- * Return the file system path that this File object points to.
- *
- * The returned path will use POSIX separators (even on Windows).
- *
- * This method is a bit different from the other methods on the Electron
- * object in the sense that there is no actual IPC happening - the
- * implementation of this method is completely in the preload script. Thus
- * we can pass it an otherwise unserializable File object.
- *
- * Consequently, it is also _not_ async.
- */
pathForFile: (file: File) => string;
-
- /**
- * Perform any logout related cleanup of native side state.
- */
logout: () => Promise<void>;
-
- /**
- * Return the previously saved user's master key from the persistent safe
- * storage accessible to the desktop app.
- *
- * The key is returned as a base64 encoded string.
- *
- * If the key is not found, return `undefined`.
- *
- * See also: {@link saveMasterKeyInSafeStorage}.
- */
masterKeyFromSafeStorage: () => Promise<string | undefined>;
-
- /**
- * Save the given {@link masterKey} (encoded as a base64 string) to the
- * persistent safe storage accessible to the desktop app.
- */
saveMasterKeyInSafeStorage: (masterKey: string) => Promise<void>;
-
- /**
- * Return true when the desktop app can currently use OS safe storage.
- */
isSafeStorageAvailable: () => Promise<boolean>;
-
- /**
- * Return the persisted desktop app-lock configuration from safe storage, if
- * any.
- */
appLockConfigFromSafeStorage: () => Promise<
PersistedAppLockConfig | undefined
>;
-
- /**
- * Save the given desktop app-lock configuration to safe storage.
- */
saveAppLockConfigInSafeStorage: (
config: PersistedAppLockConfig,
) => Promise<void>;
-
- /**
- * Remove any persisted desktop app-lock configuration from safe storage.
- */
clearAppLockConfigFromSafeStorage: () => Promise<void>;
-
- /**
- * Set or clear the callback {@link cb} to invoke whenever the app comes
- * into the foreground. More precisely, the callback gets invoked when the
- * main window gets focus.
- *
- * Setting a callback clears any previous callbacks.
- *
- * @param cb The function to call when the main window gets focus. Pass
- * `undefined` to clear the callback.
- */
onMainWindowFocus: (cb: (() => void) | undefined) => void;
-
- /**
- * Set or clear the callback {@link cb} to invoke whenever the app goes to
- * the background. More precisely, the callback gets invoked when the main
- * window blurs and the app is no longer focused.
- *
- * Setting a callback clears any previous callbacks.
- *
- * @param cb The function to call when the app is backgrounded. Pass
- * `undefined` to clear the callback.
- */
onMainWindowBlur: (cb: (() => void) | undefined) => void;
-
- /**
- * Set or clear the callback {@link cb} to invoke whenever the app gets
- * asked to open a deeplink that begins with "ente://". This allows the
- * Node.js layer to ask the renderer to handle deeplinks and redirect itself
- * to a new location if needed.
- *
- * In particular, this is necessary for handling passkey authentication.
- * See: [Note: Passkey verification in the desktop app]
- *
- * Setting a callback clears any previous callbacks.
- *
- * @param cb The function to call when the app gets asked to open a
- * "ente://" URL. The URL string (a.k.a. "deeplink") we were asked to open
- * is passed to the function verbatim.
- */
onOpenEnteURL: (cb: ((url: string) => void) | undefined) => void;
-
- /**
- * Get the persisted version for the last shown changelog.
- *
- * See: [Note: Conditions for showing "What's new"]
- */
lastShownChangelogVersion: () => Promise<number | undefined>;
-
- /**
- * Save the given {@link version} to disk as the version of the last shown
- * changelog.
- *
- * The value is saved to a store which is not cleared during logout.
- *
- * @see {@link lastShownChangelogVersion}
- */
setLastShownChangelogVersion: (version: number) => Promise<void>;
-
- /**
- * Return true if the auto launch on system startup is enabled.
- */
isAutoLaunchEnabled: () => Promise<boolean>;
-
- /**
- * Toggle the auto launch on system startup behaviour.
- *
- * @see {@link isAutoLaunchEnabled}
- */
toggleAutoLaunch: () => Promise<void>;
-
- /**
- * Return native device lock capability details for the current machine.
- *
- * Includes whether native auth is available, provider metadata, and a
- * reason when unavailable.
- */
getNativeDeviceLockCapability: () => Promise<NativeDeviceLockCapability>;
-
- /**
- * Prompt native device lock authentication.
- *
- * The {@link reason} can be shown by the OS in the native auth prompt.
- * Returns true on successful authentication.
- */
promptDeviceLock: (reason: string) => Promise<boolean>;
- // - App update
-
- /**
- * Set or clear the callback {@link cb} to invoke whenever a new
- * (actionable) app update is available. This allows the Node.js layer to
- * ask the renderer to show an "Update available" dialog to the user.
- *
- * Setting a callback clears any previous callbacks.
- */
onAppUpdateAvailable: (
cb: ((update: AppUpdate) => void) | undefined,
) => void;
-
- /**
- * Restart the app to apply the latest available update.
- *
- * This is expected to be called in response to {@link onAppUpdateAvailable}
- * if the user so wishes.
- */
updateAndRestart: () => void;
-
- /**
- * Mute update notifications for the given {@link version}. This allows us
- * to implement the "Install on next launch" functionality in response to
- * the {@link onAppUpdateAvailable} event.
- */
updateOnNextRestart: (version: string) => void;
-
- /**
- * Skip the app update with the given {@link version}.
- *
- * This is expected to be called in response to {@link onAppUpdateAvailable}
- * if the user so wishes. It will remember this {@link version} as having
- * been marked as skipped so that we don't prompt the user again.
- */
skipAppUpdate: (version: string) => void;
- // - FS
-
- /**
- * A subset of file system access APIs.
- *
- * The renderer process, being a web process, does not have full access to
- * the local file system apart from files explicitly dragged and dropped (or
- * selected by the user in a native file open dialog).
- *
- * The main process, however, has full fil system access (limited only be an
- * OS level sandbox on the entire process).
- *
- * When we're running in the desktop app, we want to better utilize the
- * local file system access to provide more integrated features to the user;
- * things that are not currently possible using web technologies. For
- * example, continuous exports to an arbitrary user chosen location on disk,
- * or watching some folders for changes and syncing them automatically.
- *
- * Towards this end, this fs object provides some generic file system access
- * functions that are needed for such features (in some cases, there are
- * other feature specific methods too in the top level electron object).
- */
fs: {
- /** Return true if there is an item at the given {@link path}. */
exists: (path: string) => Promise<boolean>;
-
- /**
- * Equivalent of `mkdir -p`.
- *
- * Create a directory at the given path if it does not already exist.
- * Any parent directories in the path that don't already exist will also
- * be created recursively, i.e. this command is analogous to an running
- * `mkdir -p`.
- */
mkdirIfNeeded: (dirPath: string) => Promise<void>;
-
- /** Rename {@link oldPath} to {@link newPath} */
rename: (oldPath: string, newPath: string) => Promise<void>;
-
- /**
- * Equivalent of `rmdir`.
- *
- * Delete the directory at the {@link path} if it is empty.
- */
rmdir: (path: string) => Promise<void>;
-
- /**
- * Equivalent of `rm`.
- *
- * Delete the file at {@link path}.
- */
rm: (path: string) => Promise<void>;
-
- /** Read the string contents of a file at {@link path}. */
readTextFile: (path: string) => Promise<string>;
-
- /**
- * Write a string to a file, replacing the file if it already exists.
- *
- * @param path The path of the file.
- * @param contents The string contents to write.
- */
writeFile: (path: string, contents: string) => Promise<void>;
-
- /**
- * A variant of {@link writeFile} that first writes the file to a backup
- * file, and then renames the backup file to the actual path. This both
- * makes the write atomic (as far as the node's fs.rename guarantees
- * atomicity), and also keeps the backup file around for recovery if
- * something goes wrong during the rename.
- *
- * This behaviour of this function is tailored around for writes to the
- * "export_status.json" during exports.
- */
writeFileViaBackup: (path: string, contents: string) => Promise<void>;
-
- /**
- * Return true if there is an item at {@link dirPath}, and it is as
- * directory.
- */
isDir: (dirPath: string) => Promise<boolean>;
-
- /**
- * Return the last modified time (integral epoch milliseconds) of the
- * file system entry at {@link path}.
- */
statMtime: (path: string) => Promise<number>;
-
- /**
- * Return the paths of all the files under the given folder.
- *
- * This function walks the directory tree starting at {@link folderPath}
- * and returns a list of the absolute paths of all the files that exist
- * therein. It will recursively traverse into nested directories, and
- * return the absolute paths of the files there too.
- *
- * The returned paths are guaranteed to use POSIX separators ('/').
- */
findFiles: (folderPath: string) => Promise<string[]>;
};
- // - Conversion
-
- /**
- * Try to convert an arbitrary image into JPEG using native layer tools.
- *
- * The behaviour is OS dependent. On macOS we use the `sips` utility, while
- * on Linux and Windows we use a `vips` bundled with our desktop app.
- *
- * @param imageData The raw image data (the contents of the image file).
- *
- * @returns JPEG data of the converted image.
- */
convertToJPEG: (imageData: Uint8Array) => Promise<Uint8Array<ArrayBuffer>>;
-
- /**
- * Generate a JPEG thumbnail for the given image.
- *
- * The behaviour is OS dependent. On macOS we use the `sips` utility, while
- * on Linux and Windows we use a `vips` bundled with our desktop app.
- *
- * @param pathOrZipItem The file whose thumbnail we want to generate. It can
- * be provided as raw image data (the contents of the image file), or the
- * path to the image file, or a tuple containing the path of the zip file
- * along with the name of an entry in it.
- *
- * @param maxDimension The maximum width or height of the generated
- * thumbnail.
- *
- * @param maxSize Maximum size (in bytes) of the generated thumbnail.
- *
- * @returns JPEG data of the generated thumbnail.
- */
generateImageThumbnail: (
pathOrZipItem: string | ZipItem,
maxDimension: number,
maxSize: number,
) => Promise<Uint8Array<ArrayBuffer>>;
-
- /**
- * Execute a FFmpeg {@link command} on the given {@link pathOrZipItem}.
- *
- * This executes the command using a FFmpeg executable we bundle with our
- * desktop app. We also have a Wasm FFmpeg implementation that we use when
- * running on the web, which has a sibling function with the same
- * parameters. See [Note:FFmpeg in Electron].
- *
- * @param command An array of strings, each representing one positional
- * parameter in the command to execute. Placeholders for the input, output
- * and ffmpeg's own path are replaced before executing the command
- * (respectively {@link inputPathPlaceholder},
- * {@link outputPathPlaceholder}, {@link ffmpegPathPlaceholder}).
- *
- * @param pathOrZipItem The path to the input file on the user's local disk,
- * or the path to a zip file on the user's disk and the name of an entry in
- * it. In the second case, the data gets serialized to a temporary file, and
- * then that path (or if it was already a path) gets substituted in the
- * FFmpeg {@link command} in lieu of {@link inputPathPlaceholder}.
- *
- * @param outputFileExtension The extension (without the dot, e.g. "jpeg")
- * to use for the output file that we ask FFmpeg to create in
- * {@param command}. While this file will eventually get deleted, and we'll
- * just return its contents, for some FFmpeg command the extension matters
- * (e.g. conversion to a JPEG fails if the extension is arbitrary).
- *
- * @returns The contents of the output file produced by the ffmpeg command
- * (specified as {@link outputPathPlaceholder} in {@link command}).
- */
ffmpegExec: (
command: FFmpegCommand,
pathOrZipItem: string | ZipItem,
outputFileExtension: string,
) => Promise<Uint8Array<ArrayBuffer>>;
-
- /**
- * Determine the duration (in seconds) of the video present at
- * {@link pathOrZipItem} using ffmpeg.
- *
- * This is a bespoke variant of {@link ffmpegExec} for the sole purpose of
- * retrieving the video duration.
- *
- * @param pathOrZipItem The input file whose duration we want to determine.
- * For more details, see the documentation of the {@link ffmpegExec}
- * parameter with the same name.
- *
- * @returns The duration (in seconds) of the video referred to by
- * {@link pathOrZipItem}.
- */
ffmpegDetermineVideoDuration: (
pathOrZipItem: string | ZipItem,
) => Promise<number>;
- // - Utility process
-
- /**
- * Trigger the creation of a new utility process of the given {@link type},
- * terminating the older ones (if any).
- *
- * This creates a new Node.js utility process, and sets things up so that we
- * can communicate directly with that utility process using a
- * {@link MessagePort} that gets posted on the "utilityProcessPort/<type>"
- * channel.
- *
- * The code running in the utility process is determined by the specific
- * value of {@link type}. Thus, att the other end of that port will be an
- * object that conforms to:
- *
- * - {@link ElectronMLWorker} interface, when type is "ml".
- *
- * For more details about the IPC flow, see: [Note: ML IPC].
- *
- * Note: For simplicity of implementation, we assume that there is at most
- * one outstanding call to {@link triggerCreateUtilityProcess} for a given
- * {@link type}.
- */
triggerCreateUtilityProcess: (type: UtilityProcessType) => void;
- // - Watch
-
- /**
- * Interface with the file system watcher running in our Node.js layer.
- *
- * [Note: Folder vs Directory in the context of FolderWatch-es]
- *
- * A note on terminology: The word "folder" is used to the top level root
- * folder for which a {@link FolderWatch} has been added. This folder is
- * also in 1-1 correspondence to be a directory on the user's disk. It can
- * have other, nested directories too (which may or may not be getting
- * mapped to separate Ente collections), but we'll not refer to these nested
- * directories as folders - only the root of the tree, which the user
- * dragged/dropped or selected to set up the folder watch, will be referred
- * to as a folder when naming things.
- */
watch: {
- /**
- * Return the list of folder watches, pruning non-existing directories.
- *
- * The list of folder paths (and auxiliary details) is persisted in the
- * Node.js layer. The implementation of this function goes through the
- * list, permanently removes any watches whose on-disk directory is no
- * longer present, and returns this pruned list of watches.
- */
get: () => Promise<FolderWatch[]>;
-
- /**
- * Add a new folder watch for the given {@link folderPath}.
- *
- * This adds a new entry in the list of watches (persisting them on
- * disk), and also starts immediately observing for file system events
- * that happen within {@link folderPath}.
- *
- * @param collectionMapping Determines how nested directories (if any)
- * get mapped to Ente collections.
- *
- * @returns The updated list of watches.
- */
add: (
folderPath: string,
collectionMapping: CollectionMapping,
) => Promise<FolderWatch[]>;
-
- /**
- * Remove the pre-existing watch for the given {@link folderPath}.
- *
- * Persist this removal, and also stop listening for file system events
- * that happen within the {@link folderPath}.
- *
- * @returns The updated list of watches.
- */
remove: (folderPath: string) => Promise<FolderWatch[]>;
-
- /**
- * Update the list of synced files for the folder watch associated
- * with the given {@link folderPath}.
- */
updateSyncedFiles: (
syncedFiles: FolderWatch["syncedFiles"],
folderPath: string,
) => Promise<void>;
-
- /**
- * Update the list of ignored file paths for the folder watch
- * associated with the given {@link folderPath}.
- */
updateIgnoredFiles: (
ignoredFiles: FolderWatch["ignoredFiles"],
folderPath: string,
) => Promise<void>;
-
- /**
- * Register the function to invoke when a file is added in one of the
- * folders we are watching.
- *
- * The callback function is passed the path to the file that was added,
- * and the folder watch it was associated with.
- *
- * The path is guaranteed to use POSIX separators ('/').
- */
onAddFile: (f: (path: string, watch: FolderWatch) => void) => void;
-
- /**
- * Register the function to invoke when a file is removed in one of the
- * folders we are watching.
- *
- * The callback function is passed the path to the file that was
- * removed, and the folder watch it was associated with.
- *
- * The path is guaranteed to use POSIX separators ('/').
- */
onRemoveFile: (f: (path: string, watch: FolderWatch) => void) => void;
-
- /**
- * Register the function to invoke when a directory is removed in one of
- * the folders we are watching.
- *
- * The callback function is passed the path to the directory that was
- * removed, and the folder watch it was associated with.
- *
- * The path is guaranteed to use POSIX separators ('/').
- */
onRemoveDir: (f: (path: string, watch: FolderWatch) => void) => void;
};
- // - Upload
-
- /**
- * Get the list of files that are present in the given zip file.
- *
- * @param zipPath The path of the zip file on the user's local file system.
- *
- * @returns A list of (zipPath, entryName) tuples, one for each file in the
- * given zip. Directories are traversed recursively, but the directory
- * entries themselves will be excluded from the returned list. File entries
- * whose file name begins with a dot (i.e. "hidden" files) will also be
- * excluded.
- *
- * Alongside `items`, the result includes `preUploadSkippedFiles`: the
- * hidden entries excluded above, plus a single entry for the zip itself if
- * it could not be opened.
- *
- * To read the contents of the files themselves, see [Note: IPC streams].
- */
listZipItems: (
zipPath: string,
) => Promise<{
items: ZipItem[];
preUploadSkippedFiles: PreUploadSkippedFile[];
}>;
-
- /**
- * Return the size in bytes of the file at the given path or of a particular
- * entry within a zip file.
- */
pathOrZipItemSize: (pathOrZipItem: string | ZipItem) => Promise<number>;
-
- /**
- * Return any pending uploads that were previously enqueued but haven't yet
- * been completed.
- *
- * Return undefined if there are no such pending uploads.
- *
- * The state of pending uploads is persisted in the Node.js layer. Or app
- * start, we read in this data from the Node.js layer via this IPC method.
- * The Node.js code returns the persisted data after filtering out any files
- * that no longer exist on disk.
- */
pendingUploads: () => Promise<PendingUploads | undefined>;
-
- /**
- * Set the state of pending uploads.
- *
- * - Typically, this would be called at the start of an upload.
- *
- * - Thereafter, as each item gets uploaded one by one, we'd call
- * {@link markUploadedFile} or {@link markUploadedZipItem}.
- *
- * - Finally, once the upload completes (or gets cancelled), we'd call
- * {@link clearPendingUploads} to complete the circle.
- */
setPendingUploads: (pendingUploads: PendingUploads) => Promise<void>;
-
- /**
- * Mark the given files (specified by their disk paths) as having been
- * uploaded.
- *
- * @param {@link path} The path to the file system file which was uploaded.
- *
- * @param {@link associatedPath} The path file (if any) of the file
- * associated with the file which was uploaded. This will be present only in
- * the case of live photos, where this will be set to the path of the video
- * component of the live photo on disk.
- *
- * @returns The last modified time (epoch milliseconds) of the file at
- * {@link path}.
- */
markUploadedFile: (
path: string,
associatedPath?: string,
) => Promise<number>;
-
- /**
- * Mark the given {@link ZipItem}s as having been uploaded.
- *
- * @param {@link item} The {@link ZipItem} which was uploaded.
- *
- * @param {@link associatedItem} An optional extra {@link ZipItem}
- * associated with the {@link item} which was uploaded. This will be present
- * only in case of live photos, where this'll be set to the {@link ZipItem}
- * representing the video component of the live photo on disk.
- *
- * @returns The last modified time (epoch milliseconds) of the zip file
- * containing {@link item}.
- */
markUploadedZipItem: (
item: ZipItem,
associatedItem?: ZipItem,
) => Promise<number>;
-
- /**
- * Clear any pending uploads.
- *
- * This is also taken by the Node.js layer as a signal to clear any cached
- * state it has kept around to speed up the upload.
- */
clearPendingUploads: () => Promise<void>;
}
export type UtilityProcessType = "ml";
-/**
- * The shape of the object exposed by the Node.js utility process listening on
- * the other side message port that the web layer obtains by doing
- * {@link triggerCreateUtilityProcess} with type "ml".
- */
export interface ElectronMLWorker {
- /**
- * Return the last modified time (epoch milliseconds) for the file at the
- * given {@link path} on the user's file system.
- */
fsStatMtime: (path: string) => Promise<number>;
-
- /**
- * Analyze a single image with the Rust ML pipeline, computing the indexes
- * (faces, CLIP) that are enabled in the request.
- *
- * The image is decoded, preprocessed, run through the ONNX models, and
- * postprocessed entirely on the native side (by the Rust crate shared
- * with the other Ente clients); we get back the final results.
- *
- * See: [Note: ML with Rust]
- */
analyzeImage: (
request: MLWorkerAnalyzeImageRequest,
) => Promise<MLWorkerAnalyzeImageResponse>;
-
- /**
- * Release the (pinned) native ML sessions.
- *
- * Invoked when indexing goes idle so that the utility process doesn't
- * hold on to the model memory while there is nothing to do. Sessions are
- * transparently recreated on the next {@link analyzeImage}.
- */
releaseMLRuntime: () => Promise<void>;
-
- /**
- * Return a CLIP embedding of the given text if we already have the model
- * downloaded and prepped. If the model is not available return `undefined`.
- *
- * This differs from the other sibling ML functions in that it doesn't wait
- * for the model download to finish. It does trigger a model download, but
- * then immediately returns `undefined`. At some future point, when the
- * model downloaded finishes, calls to this function will start returning
- * the result we seek.
- *
- * The reason for doing it in this asymmetric way is because CLIP text
- * embeddings are used as part of deducing user initiated search results,
- * and we don't want to block that interaction on a large network request.
- *
- * See: [Note: Natural language search using CLIP]
- *
- * @param text The string whose embedding we want to compute.
- *
- * @returns A CLIP embedding (a normalized array of 512 floating point
- * values).
- */
computeCLIPTextEmbeddingIfAvailable: (
text: string,
) => Promise<Float32Array | undefined>;
}
-/**
- * A request to index a single image via {@link ElectronMLWorker.analyzeImage}.
- */
export interface MLWorkerAnalyzeImageRequest {
- /** The ID of the {@link EnteFile} being indexed. */
fileID: number;
- /**
- * Path to the image on the user's local file system. Exactly one of
- * {@link path} and {@link bytes} should be provided.
- */
path?: string | undefined;
- /**
- * The (encoded) contents of the image, in any supported format; the
- * native side takes care of decoding.
- */
bytes?: Uint8Array | undefined;
- /** Compute the face related parts of the index. */
runFaces: boolean;
- /** Compute the CLIP image embedding. */
runClip: boolean;
- /** Run the pet recognition models (feature in development). */
runPets: boolean;
- /**
- * When set, the result will carry a JPEG face crop for each detected
- * face.
- */
generateFaceCrops: boolean;
}
-/**
- * Broad category for an error encountered while analyzing an image.
- *
- * Only `image` indicates a permanent problem inherent to the image. `init`
- * blocks indexing for the lifetime of the utility process (this includes
- * corrupt on-disk models, which won't fix themselves and need manual
- * intervention), while `ort` and `misc` remain retryable. None of those other
- * kinds should permanently mark the file as unindexable.
- */
export type MLWorkerAnalyzeImageErrorKind = "init" | "ort" | "image" | "misc";
-/** An error returned by the Electron ML utility process. */
export interface MLWorkerAnalyzeImageError {
kind: MLWorkerAnalyzeImageErrorKind;
message: string;
}
-/**
- * Result envelope for an image analysis request.
- *
- * This explicit envelope is used instead of throwing a custom `Error` because
- * Comlink only preserves an error's name, message and stack.
- */
export type MLWorkerAnalyzeImageResponse =
| { ok: true; result: MLWorkerAnalyzeImageResult }
| { ok: false; error: MLWorkerAnalyzeImageError };
-/**
- * A face detected by {@link ElectronMLWorker.analyzeImage}.
- *
- * All coordinates are relative (normalized to 0-1 by the dimensions of the
- * image).
- */
export interface MLWorkerFaceResult {
- /**
- * The face ID. Same format as the faceIDs the web pipeline used to
- * generate: `{fileID}_{xMin}_{yMin}_{xMax}_{yMax}`.
- */
faceId: string;
- detection: {
- score: number;
- /** Relative [xMin, yMin, xMax, yMax]. */
- boxXyxy: number[];
- /**
- * 5 relative [x, y] landmarks: leftEye, rightEye, nose, leftMouth,
- * rightMouth.
- */
- keypoints: number[][];
- };
+ detection: { score: number; boxXyxy: number[]; keypoints: number[][] };
blurValue: number;
- /** The face embedding (192 floating point values). */
embedding: Float32Array<ArrayBuffer>;
}
-/**
- * The result of an {@link ElectronMLWorker.analyzeImage} call.
- *
- * This mirrors the result produced by the Rust pipeline (only the parts of
- * the index that were enabled in the request are present).
- */
export interface MLWorkerAnalyzeImageResult {
fileId: number;
- /** The dimensions of the decoded image (after orientation correction). */
decodedImageSize: { width: number; height: number };
- /** Present when the request had {@link runFaces} set. */
faces?: MLWorkerFaceResult[];
- /**
- * JPEG blobs of the crops of detected faces, index-aligned with
- * {@link faces}. Present when the request had {@link generateFaceCrops}
- * set. Crop generation is best effort: a face whose crop could not be
- * generated has a `null` in its slot.
- */
faceCrops?: (Uint8Array<ArrayBuffer> | null)[];
- /** Present when the request had {@link runClip} set. */
- clip?: {
- /** The (normalized) CLIP image embedding (512 floating point values). */
- embedding: Float32Array<ArrayBuffer>;
- };
- /** Pet recognition results (feature in development, ignored for now). */
+ clip?: { embedding: Float32Array<ArrayBuffer> };
petFaces?: unknown;
petBodies?: unknown;
- /**
- * True when any model that contributed to this result ran on the
- * respective accelerated execution provider.
- */
usedCoreml: boolean;
usedWebgpu: boolean;
}
-/**
- * Data passed across the IPC bridge when an app update is available.
- */
export interface AppUpdate {
- /** `true` if the user automatically update to this (new) version */
autoUpdatable: boolean;
- /** The new version that is available */
version: string;
}
-/**
- * A top level folder that was selected by the user for watching.
- *
- * The user can set up multiple such watches. Each of these can in turn be
- * syncing multiple on disk folders to one or more Ente collections (depending
- * on the value of {@link collectionMapping}).
- *
- * This type is passed across the IPC boundary. It is persisted on the Node.js
- * side.
- */
export interface FolderWatch {
- /**
- * Specify if nested files should all be mapped to the same single root
- * collection, or if there should be a collection per directory that has
- * files. @see {@link CollectionMapping}.
- */
collectionMapping: CollectionMapping;
- /**
- * The path to the (root) folder we are watching.
- */
folderPath: string;
- /**
- * Files that have already been uploaded.
- */
syncedFiles: FolderWatchSyncedFile[];
- /**
- * Files (paths) that should be ignored when uploading.
- */
ignoredFiles: string[];
- /**
- * Whether the folder is currently accessible on disk.
- *
- * Folders on ejected external drives will have this set to false. This
- * property is not persisted and is computed each time the watch list is
- * fetched.
- */
isAccessible?: boolean;
}
-/**
- * The ways in which directories are mapped to collection.
- *
- * This comes into play when we have nested directories that we are trying to
- * upload or watch on the user's local file system.
- */
-export type CollectionMapping =
- /** All files go into a single collection named after the root directory. */
- | "root"
- /** Each file goes to a collection named after its parent directory. */
- | "parent";
-
-/**
- * An on-disk file that was synced as part of a folder watch.
- */
+export type CollectionMapping = "root" | "parent";
export interface FolderWatchSyncedFile {
path: string;
uploadedFileID: number;
collectionID: number;
}
-/**
- * A particular file within a zip file.
- *
- * When the user uploads a zip file, we create a "zip item" for each entry
- * within the zip file. Each such entry is a tuple containing the (path to a zip
- * file itself, and the name of an entry within it).
- *
- * The name of the entry is not just the file name, but rather is the full path
- * of the file within the zip. That is, each entry name uniquely identifies a
- * particular file within the given zip.
- *
- * When `entryName` is a path within a nested directory, it is guaranteed to use
- * the POSIX path separator ("/") since that is the path separator required by
- * the ZIP format itself
- *
- * > 4.4.17.1 The name of the file, with optional relative path.
- * >
- * > The path stored MUST NOT contain a drive or device letter, or a leading
- * > slash. All slashes MUST be forward slashes '/' as opposed to backwards
- * > slashes '\' for compatibility with Amiga and UNIX file systems etc. If
- * > input came from standard input, there is no file name field.
- * >
- * > https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
- */
export type ZipItem = [zipPath: string, entryName: string];
export interface PreUploadSkippedFile {
@@ -999,52 +205,13 @@ export interface PreUploadSkippedFile {
type: "hiddenFile" | "failedZip";
}
-/**
- * State about pending and in-progress uploads.
- *
- * When the user starts an upload, we remember the files they'd selected (or
- * drag-dropped) so that we can resume if they restart the app in before the
- * uploads have been completed. This state is kept on the Electron side, and
- * this object is the IPC intermediary.
- */
export interface PendingUploads {
- /**
- * The collection to which we're uploading, or the root collection.
- *
- * This is name of the collection (when uploading to a singular collection)
- * or the root collection (when uploading to separate * albums) to which we
- * these uploads are meant to go to. See {@link CollectionMapping}.
- *
- * It will not be set if we're just uploading standalone files.
- */
collectionName?: string;
- /**
- * Paths of regular files that need to be uploaded.
- */
filePaths: string[];
- /**
- * {@link ZipItem} (zip path and entry name) that need to be uploaded.
- */
zipItems: ZipItem[];
- /**
- * Files that were skipped because either we could not open them (zip files)
- * or they are hidden dot files.
- */
preUploadSkippedFiles?: PreUploadSkippedFile[];
- /** Whether Takeout-favorited uploads should be added to Favorites. */
importTakeoutFavorites?: boolean;
- /** Whether media originating from Google Photos partner sharing is uploaded. */
includePartnerSharedFiles?: boolean;
}
-/**
- * A command that we can ask FFmpeg to run for us.
- *
- * [Note: Alternative FFmpeg command for HDR videos]
- *
- * Usually, this is a single command (specified as an array of strings
- * containing the "words" of the command). However, we can also provide two
- * alternative commands - one to run when the input is (heuristically) detected
- * as a HDR video, and one otherwise.
- */
export type FFmpegCommand = string[] | { default: string[]; hdr: string[] };
diff --git a/web/packages/gallery/components/FileInfo.tsx b/web/packages/gallery/components/FileInfo.tsx
index 4bcbbc377d..4a5f7a6d05 100644
--- a/web/packages/gallery/components/FileInfo.tsx
+++ b/web/packages/gallery/components/FileInfo.tsx
@@ -1,10 +1,9 @@
/* eslint-disable @typescript-eslint/ban-ts-comment */
-/* TODO: Split this file to deal with the ente-new/photos imports.
-1. Move common components into FileInfoComponents.tsx
-2. Move the rest out to files in the apps themselves:
- - albums/SharedFileInfo
- - photos/FileInfo
-*/
+// TODO: Split this file to deal with the ente-new/photos imports.
+// 1. Move common components into FileInfoComponents.tsx
+// 2. Move the rest out to files in the apps themselves:
+// - albums/SharedFileInfo
+// - photos/FileInfo
import CalendarTodayIcon from "@mui/icons-material/CalendarToday";
import CameraOutlinedIcon from "@mui/icons-material/CameraOutlined";
@@ -94,9 +93,9 @@ import { t } from "i18next";
import React, { useEffect, useMemo, useRef, useState } from "react";
import { Trans } from "react-i18next";
-// Re-uses images from ~leaflet package.
import "leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css";
import "leaflet/dist/leaflet.css";
+// Reuse Leaflet's bundled marker images.
// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unused-expressions
haveWindow() && require("leaflet-defaulticon-compatibility");
const leaflet = haveWindow()
@@ -104,99 +103,27 @@ const leaflet = haveWindow()
(require("leaflet") as typeof import("leaflet"))
: null;
-/**
- * Exif data for a file, in a form suitable for use by {@link FileInfo}.
- *
- * TODO: Indicate missing exif (e.g. videos) better, both in the data type, and
- * in the UI (e.g. by omitting the entire row).
- */
+// TODO: Indicate missing exif (e.g. videos) better, both in the data type, and
+// in the UI (e.g. by omitting the entire row).
export interface FileInfoExif {
tags: RawExifTags | undefined;
parsed: ParsedMetadata | undefined;
}
export type FileInfoProps = ModalVisibilityProps & {
- /**
- * The file whose information we are showing.
- */
file: EnteFile;
- /**
- * Exif information for {@link file}.
- */
exif: FileInfoExif | undefined;
- /**
- * If set, then controls to edit the file's metadata (name, date, caption)
- * will be shown.
- */
allowEdits?: boolean;
- /**
- * If set, then an inline map will be shown (if the user has enabled it)
- * using the file's location.
- */
allowMap?: boolean;
- /**
- * If set, then a chip will be shown for each collection that this file is
- * a part of.
- *
- * Uses {@link fileCollectionIDs}, {@link collectionNameByID} and
- * {@link onSelectCollection}, so all of those props should also be set for
- * this to have an effect.
- */
showCollections?: boolean;
- /**
- * A map from file IDs to the IDs of the collections that they're a part of.
- *
- * Used when {@link showCollections} is set.
- */
fileCollectionIDs?: Map<number, number[]>;
- /**
- * A map from collection IDs to their name.
- *
- * Used when {@link showCollections} is set.
- */
collectionNameByID?: Map<number, string>;
- /**
- * IDs of hidden collections.
- *
- * Used when {@link showCollections} is set.
- */
hiddenCollectionIDs?: Set<number>;
- /**
- * Called when the action on the file info drawer has changed some metadata
- * for a file.
- *
- * It should return a promise that settles when the changes have been
- * reflected locally. Until the promise settles the UI element that
- * triggered the change will show an activity indicator to the user.
- */
onFileMetadataUpdate?: () => Promise<void>;
- /**
- * Called when an action on the file info drawer change the caption of the
- * given {@link EnteFile}.
- *
- * This hook allows the file viewer to update the caption it is displaying
- * for the given file. It is called in addition to, and after the settlement
- * of, {@link onFileMetadataUpdate} since the caption update requires a
- * special case refresh of the PhotoSwipe dialog.
- *
- * @param fileID The ID of the file whose caption was updated.
- *
- * @param newCaption The updated value of the file's caption.
- */
+ // PhotoSwipe needs a separate refresh after caption metadata settles.
onUpdateCaption: (fileID: number, newCaption: string) => void;
- /**
- * Called when the user selects a collection from among the collections that
- * the file belongs to.
- */
onSelectCollection?: (collectionID: number) => void;
- /**
- * Called when the user selects a person in the file info panel.
- */
onSelectPerson?: (personID: string) => void;
- /**
- * Called when an edit surface owned by the file info panel is opened or
- * closed, so the viewer can avoid navigating to another file underneath it.
- */
onNavigationLockChange?: (locked: boolean) => void;
};
@@ -261,7 +188,6 @@ export const FileInfo: React.FC<FileInfoProps> = ({
const canAddPerson = isMLEnabled() && assignablePeople.length > 0;
- // Prefer the location in the EnteFile, then fall back to Exif.
const fileLocationValue = fileLocation(file) ?? exif?.parsed?.location;
const location = fileLocationValue;
@@ -271,19 +197,7 @@ export const FileInfo: React.FC<FileInfoProps> = ({
useEffect(() => {
if (!isMLEnabled()) return undefined;
- // Take a dependency on open so that we refresh the list of people by
- // calling `getAnnotatedFacesForFile` again when the file info dialog is
- // closed and reopened.
- //
- // This covers a scenario like:
- // - User opens file info panel
- // - Selects one of the faces
- // - Gives it a name
- // - Then opens the same file again, and reopens the file info panel.
- //
- // Since the `file` hasn't changed, this hook wouldn't rerun. So we also
- // take a dependency on the open state of the dialog, causing us to
- // rerun whenever reopened (even if for the same file).
+ // Naming a face does not change file identity; reopening must refetch it.
if (!open) return undefined;
setAnnotatedFaces([]);
@@ -624,10 +538,6 @@ const NavigationHintSeparator: React.FC<React.PropsWithChildren> = ({
</Typography>
);
-/**
- * Some immediate fields of interest, in the form that we want to display on the
- * info panel for a file.
- */
type AnnotatedExif = Required<FileInfoExif> & {
resolution?: string;
megaPixels?: string;
@@ -658,11 +568,10 @@ const annotateExif = (
if (exif.Make && exif.Model)
info.takenOnDevice = `${exif.Make.description} ${exif.Model.description}`;
- if (exif.FNumber)
- info.fNumber = exif.FNumber.description; /* e.g. "f/16" */
+ if (exif.FNumber) info.fNumber = exif.FNumber.description;
if (exif.ExposureTime)
- info.exposureTime = exif.ExposureTime.description; /* "1/10" */
+ info.exposureTime = exif.ExposureTime.description;
if (exif.ISOSpeedRatings)
info.iso = `ISO${tagNumericValue(exif.ISOSpeedRatings)}`;
@@ -676,25 +585,12 @@ const FileInfoSidebar = styled(
<SidebarDrawer
{...props}
anchor="right"
- // See: [Note: Workarounds for unactionable ARIA warnings], but this
- // time with a different workaround.
- //
- // https://github.com/mui/material-ui/issues/43106#issuecomment-2514637251
+ // Avoid MUI's aria-hidden focus warning when this closes.
disableRestoreFocus={true}
closeAfterTransition={true}
/>
),
)(({ theme }) => ({
- // [Note: Lighter backdrop for overlays on photo viewer]
- //
- // The default backdrop color we use for the drawer in light mode is too
- // "white" when used in the image gallery because unlike the rest of the app
- // the gallery retains a black background irrespective of the mode. So use a
- // lighter scrim when overlaying content directly atop the image gallery.
- //
- // We don't need to add this special casing for nested overlays (e.g.
- // dialogs initiated from the file info drawer itself) since now there is
- // enough "white" on the screen to warrant the stronger (default) backdrop.
...theme.applyStyles("light", {
".MuiBackdrop-root": {
backgroundColor: theme.vars.palette.backdrop.faint,
@@ -712,32 +608,12 @@ const BottomAlignedFileInfoSidebar = styled(FileInfoSidebar)({
});
interface InfoItemProps {
- /**
- * The icon associated with the info entry.
- */
icon: React.ReactNode;
- /**
- * The primary content / title of the info entry.
- *
- * Only used if {@link children} are not specified.
- */
title?: string;
- /**
- * The secondary information / subtext associated with the info entry.
- *
- * Only used if {@link children} are not specified.
- */
caption?: React.ReactNode;
- /**
- * A component, usually a button (e.g. an "edit button"), shown at the
- * trailing edge of the info entry.
- */
trailingButton?: React.ReactNode;
}
-/**
- * An entry in the file info panel listing.
- */
const InfoItem: React.FC<React.PropsWithChildren<InfoItemProps>> = ({
icon,
title,
@@ -779,12 +655,7 @@ const InfoItemIconContainer = styled("div")(
`,
);
-type EditButtonProps = ButtonishProps & {
- /**
- * If true, then an activity indicator is shown in place of the edit icon.
- */
- loading?: boolean;
-};
+type EditButtonProps = ButtonishProps & { loading?: boolean };
const EditButton: React.FC<EditButtonProps> = ({ onClick, loading }) => (
<IconButton onClick={onClick} disabled={!!loading} color="secondary">
@@ -846,8 +717,6 @@ const Caption: React.FC<CaptionProps> = ({
}, [onNavigationLockChange, values.caption, caption, isSaving]);
if (!caption.length && !allowEdits) {
- // Visually take up some space, otherwise the info panel for the shared
- // photos without a caption looks squished at the top.
return <Box sx={{ minHeight: 2 }}></Box>;
}
@@ -874,7 +743,6 @@ const Caption: React.FC<CaptionProps> = ({
<IconButton
type="submit"
disabled={isSaving}
- // Prevent layout shift when we're showing progress.
sx={{ minWidth: "48px" }}
>
{isSaving ? (
@@ -923,23 +791,12 @@ const CreationTime: React.FC<CreationTimeProps> = ({
const { dateTime, timestamp: editedTime } = pickedTime;
if (editedTime == originalDate.getTime()) {
- // Same as before.
return;
}
setIsSaving(true);
try {
- // [Note: Don't modify offsetTime when editing date via picker]
- //
- // Use the updated date time (both in its canonical dateTime form,
- // and also as in the epoch timestamp), but don't use the offset.
- //
- // The offset here will be the offset of the computer where this
- // user is making this edit, not the offset of the place where the
- // photo was taken. In a future iteration of the date time editor,
- // we can provide functionality for the user to edit the associated
- // offset, but right now it is not even surfaced, so don't also
- // potentially overwrite it.
+ // The picker reports this computer's offset, not the photo's.
await updateFilePublicMagicMetadata(file, { dateTime, editedTime });
await onFileMetadataUpdate?.();
} catch (e) {
@@ -1046,25 +903,7 @@ const createMultipartCaption = (
);
type RenameFileDialogProps = ModalVisibilityProps & {
- /**
- * The current name of the file.
- */
fileName: string;
- /**
- * Called when the user makes a change to the existing name and activates the
- * rename button on the dialog.
- *
- * @param newFileName The changed name. The extension currently cannot be
- * modified, but it is guaranteed the name component of {@link newFileName}
- * will be different from that of the {@link fileName} prop of the dialog.
- *
- * Until the promise settles, the dialog will show an activity indicator. If
- * the promise rejects, it will also show an error. If the promise is
- * fulfilled, then the dialog will also be closed.
- *
- * The dialog will also be closed if the user activates the rename button
- * without changing the name.
- */
onRename: (newFileName: string) => Promise<void>;
};
@@ -1100,7 +939,6 @@ const RenameFileDialog: React.FC<RenameFileDialogProps> = ({
onCancel={onClose}
slotProps={{
input: {
- // Align the adornment text to the input text.
sx: { alignItems: "baseline" },
endAdornment: extension && (
<InputAdornment position="end">
diff --git a/web/packages/gallery/components/utils/save-groups.ts b/web/packages/gallery/components/utils/save-groups.ts
index 9c068085b6..68c77fbd0e 100644
--- a/web/packages/gallery/components/utils/save-groups.ts
+++ b/web/packages/gallery/components/utils/save-groups.ts
@@ -1,131 +1,32 @@
import { useSyncExternalStore } from "react";
-/**
- * An object that keeps track of progress of a user-initiated download of a set
- * of files to the user's device.
- *
- * This "download" is distinct from the downloads the app does from remote (e.g.
- * when the user is viewing them).
- *
- * What we're doing here is perhaps more accurately described "a user initiated
- * download of files to the user's device", but that is too long, so we instead
- * refer to this process as "saving them".
- *
- * Note however that the app's UI itself takes the user perspective, so the
- * upper (UI) layers use the word "download", while this implementation layer
- * uses the word "save", and there is an unavoidable incongruity in the middle.
- */
+// "Save" here means a user-initiated download, not a cache or viewer fetch.
export interface SaveGroup {
- /**
- * A randomly generated unique identifier of this set of saves.
- */
id: number;
- /**
- * A callback to retry the download that created this save group.
- */
retry?: () => void;
- /**
- * The user visible title of the save group.
- *
- * Depending on the context can either be an auto generated string (e.g "5
- * files"), or the name of the collection which is being downloaded.
- */
title: string;
- /**
- * If this save group is associated with a {@link CollectionSummary}, then
- * the ID of that collection summary.
- *
- * The {@link SaveGroup} type is also used in the context of the albums app,
- * which does not use or need the concept of link {@link CollectionSummary},
- * we to avoid taking a dependency of the type we store these two relevant
- * properties - {@link collectionSummaryID} and
- * {@link isHiddenCollectionSummary} - inline.
- */
collectionSummaryID?: number;
- /**
- * `true` if the collection summary associated with the save group is
- * hidden.
- */
isHiddenCollectionSummary?: boolean;
- /**
- * The path to a directory on the user's file system that was selected by
- * the user to save the files in when they initiated the download on the
- * desktop app.
- *
- * This property is only set when running in the context of the desktop app.
- * The web app downloads to the user's default downloads folder, and when
- * running in the web app this property will not be set.
- */
downloadDirPath?: string;
- /**
- * The total number of files to save to the user's device.
- */
total: number;
- /**
- * The number of files that have been saved so far.
- */
success: number;
- /**
- * The number of failures.
- */
failed: number;
- /**
- * An {@link AbortController} that can be used to cancel the save.
- */
canceller: AbortController;
- /**
- * The reason for the failure, if any.
- *
- * This is used to show a more specific error message to the user.
- * - "network_offline": The network went offline during download
- * - "file_error": One or more individual files failed to download
- * - undefined: No specific reason (generic error)
- */
failureReason?: "network_offline" | "file_error";
- /**
- * `true` when we expect the ZIP download to span multiple parts, so part
- * numbers should be shown from the first part.
- */
includeZipNumber?: boolean;
- /**
- * `true` when the ZIP file is being downloaded from memory to the user's
- * device. This is only relevant for web downloads where files are first
- * collected into a ZIP in memory, then saved to the device.
- */
isDownloadingZip?: boolean;
- /**
- * The current ZIP part number being processed. Only relevant for web
- * downloads where files are batched into multiple ZIP parts.
- */
currentPart?: number;
}
-/**
- * Return `true` if there are no files in this save group that are pending.
- */
export const isSaveComplete = ({ total, success, failed }: SaveGroup) =>
total == success + failed;
-/**
- * Return `true` if there are no files in this save group that are pending, but
- * one or more files had failed to download.
- */
export const isSaveCompleteWithErrors = (group: SaveGroup) =>
group.failed > 0 && isSaveComplete(group);
-/**
- * Return `true` if this save was cancelled on a user request.
- */
export const isSaveCancelled = (group: SaveGroup) =>
group.canceller.signal.aborted;
-/**
- * A function that can be used to add a save group.
- *
- * It returns a function that can subsequently be used to update the save group
- * by applying a transform to it (see {@link UpdateSaveGroup}). The UI will
- * react and update itself on updates done this way.
- */
export type AddSaveGroup = (
group: Pick<
SaveGroup,
@@ -140,45 +41,24 @@ export type AddSaveGroup = (
>,
) => UpdateSaveGroup;
-/**
- * A function that can be used to update a instance of a save group by applying
- * the provided transform.
- *
- * This is obtained by a call to an instance of {@link AddSaveGroup}. The UI
- * will update itself to reflect the changes made by the transform.
- */
export type UpdateSaveGroup = (
tranform: (prev: SaveGroup) => SaveGroup,
) => void;
-/**
- * A function that can be used to remove a save group.
- *
- * Save groups can be removed both on user actions - if the user presses the
- * close button to discard the notification showing the status of the save group
- * (cancelling it if needed) - or programmatically, if it is found that there
- * are no files that need saving for a particular request.
- */
export type RemoveSaveGroup = (saveGroup: SaveGroup) => void;
-/**
- * Keep save groups outside the component tree so remounts can rehydrate
- * in-progress downloads after route changes.
- */
+// Module state lets route remounts rehydrate in-progress downloads.
type SaveGroupsListener = () => void;
let saveGroupsSnapshot: SaveGroup[] = [];
const listeners = new Set<SaveGroupsListener>();
-// Notify subscribers after the snapshot changes.
const emitChange = () => {
for (const listener of listeners) listener();
};
-// Return the current snapshot for external-store consumers.
const getSnapshot = () => saveGroupsSnapshot;
-// Register a listener and return its unsubscribe cleanup.
const subscribe = (listener: SaveGroupsListener) => {
listeners.add(listener);
return () => {
@@ -218,10 +98,6 @@ export const resetSaveGroups = () => {
emitChange();
};
-/**
- * A custom React hook that manages a list of active {@link SaveGroup}s, and
- * provides functions to add and remove entries to the list.
- */
export const useSaveGroups = () => {
const saveGroups = useSyncExternalStore(
subscribe,
@@ -236,12 +112,7 @@ export const useSaveGroups = () => {
};
};
-/**
- * Return save-group actions without subscribing to progress updates.
- *
- * Use this in components that only need to initiate or dismiss downloads,
- * otherwise every save progress update will re-render the caller.
- */
+// Avoid subscribing action-only callers to frequent progress updates.
export const useSaveGroupsActions = () => ({
onAddSaveGroup: addSaveGroup,
onRemoveSaveGroup: removeSaveGroup,
diff --git a/web/packages/gallery/components/viewer/FileViewer.tsx b/web/packages/gallery/components/viewer/FileViewer.tsx
index d6e0c93f21..66d38f5c33 100644
--- a/web/packages/gallery/components/viewer/FileViewer.tsx
+++ b/web/packages/gallery/components/viewer/FileViewer.tsx
@@ -100,290 +100,70 @@ const hasFileViewerBackStateMarker = (state: unknown, marker: string) =>
typeof state == "object" &&
(state as Record<string, unknown>)[fileViewerBackStateKey] == marker;
-/**
- * Derived data for a file that is needed to display the file viewer controls
- * etc associated with the file.
- *
- * This is recomputed on-demand each time the slide changes.
- */
export interface FileViewerFileAnnotation {
- /**
- * The id of the file whose annotation this is.
- */
fileID: number;
- /**
- * `true` if this file is owned by the logged in user (if any).
- */
isOwnFile: boolean;
- /**
- * `true` if the toggle favorite action should be shown for this file.
- */
showFavorite: boolean;
- /**
- * Set if the download action should be shown for this file.
- *
- * - When "bar", the action button is shown among the bar icons.
- *
- * - When "menu", the action is shown as a more menu entry.
- *
- * Note: "bar" should only be set if {@link haveUser} is also true.
- */
showDownload: "bar" | "menu" | undefined;
- /**
- * `true` if the delete action should be shown for this file.
- */
showDelete: boolean;
- /**
- * `true` if the toggle archive action should be shown for this file.
- */
showArchive: boolean;
- /**
- * `true` if the copy image action should be shown for this file.
- */
showCopyImage: boolean;
- /**
- * `true` if this is an image which can be edited, _and_ editing is
- * possible, and the edit action should therefore be shown for this file.
- */
showEditImage: boolean;
}
-/**
- * A file, its annotation, and its item data, in a nice cosy box.
- */
export interface FileViewerAnnotatedFile {
file: EnteFile;
annotation: FileViewerFileAnnotation;
itemData: ItemData;
}
-/** The type of sidebar to open initially in the file viewer. */
export type FileViewerInitialSidebar = "likes" | "comments";
export type FileViewerProps = ModalVisibilityProps & {
- /**
- * The currently logged in user, if any.
- *
- * - If we're running in the context of the photos app, then this should be
- * set to the currently logged in user.
- *
- * - If we're running in a viewer without account context, then this should
- * not be set.
- *
- * See: [Note: Gallery children can assume user]
- */
user?: LocalUser;
- /**
- * The list of files that are currently being displayed in the context in
- * which the file viewer was invoked.
- *
- * Although the file viewer is called on to display a particular file
- * (specified by the {@link initialIndex} prop), the viewer is always used
- * in the context of a an album, or search results, or some other arbitrary
- * list of files. The {@link files} prop sets this underlying list of files.
- *
- * After the initial file has been shown, the user can navigate through the
- * other files from within the viewer by using the arrow buttons.
- */
files: EnteFile[];
- /**
- * The index of the file that should be initially shown.
- *
- * Subsequently the user may navigate between files by using the controls
- * provided within the file viewer itself.
- */
initialIndex: number;
- /**
- * If set, the specified sidebar will be opened when the file viewer opens.
- */
initialSidebar?: FileViewerInitialSidebar;
- /**
- * If set, the comments sidebar will scroll to and highlight this comment.
- * Only used when initialSidebar is "comments".
- */
highlightCommentID?: string;
- /**
- * If true then the viewer does not show controls for downloading the file.
- */
disableDownload?: boolean;
- /**
- * If true then the fullscreen button is shown as a primary action button
- * in the toolbar instead of being hidden in the more menu.
- */
showFullscreenButton?: boolean;
- /**
- * `true` when we are viewing files in an album that the user does not own.
- */
isInIncomingSharedCollection?: boolean;
- /**
- * `true` when we are viewing files in the Trash.
- */
isInTrashSection?: boolean;
- /**
- * `true` when we are viewing files in the hidden section.
- */
isInHiddenSection?: boolean;
- /**
- * File IDs of all the files that the user has marked as a favorite.
- *
- * See also {@link onToggleFavorite}.
- */
favoriteFileIDs?: Set<number>;
- /**
- * File IDs of for which an update of its favorite status is pending (e.g.
- * due to a toggle favorite action in the file viewer).
- *
- * See also {@link favoriteFileIDs} and {@link onToggleFavorite}.
- */
pendingFavoriteUpdates?: Set<number>;
- /**
- * File IDs of for which an update of its visibility is pending (e.g. due to
- * a toggle archived action in the file viewer).
- *
- * See also {@link onFileVisibilityUpdate}.
- */
pendingVisibilityUpdates?: Set<number>;
- /**
- * A mapping from file IDs to the IDs of the normal (non-hidden) collections
- * that they are a part of.
- */
fileNormalCollectionIDs?: FileInfoProps["fileCollectionIDs"];
- /**
- * A mapping from file IDs to all collection IDs that they are a part of.
- */
fileCollectionIDs?: FileInfoProps["fileCollectionIDs"];
- /**
- * IDs of hidden collections.
- */
hiddenCollectionIDs?: FileInfoProps["hiddenCollectionIDs"];
- /**
- * Collection summaries indexed by their IDs.
- */
collectionSummaries?: CollectionSummaries;
- /**
- * Called when there was some update performed within the file viewer that
- * necessitates us to pull the latest updates with remote.
- *
- * This is called when the file viewer is closing if any changes were made
- * in the file info panel of the file viewer for any of the files that the
- * user was viewing (e.g. if they changed the caption).
- *
- * Those changes have already been applied to both remote, and likely
- * already also to our local state via {@link onRemoteFilesPull}. This this
- * callback is to trigger a full pull so that any discrepancies in local
- * database also gets up to speed if needed.
- *
- * If we're in a context where edits are not possible, e.g. {@link user} is
- * not defined, then this prop is not used and need not be provided.
- */
onTriggerRemotePull?: () => void;
- /**
- * Called when an action in the file viewer requires us to pull the local
- * files and collections with remote.
- *
- * Unlike {@link onTriggerRemotePull}, which is a trigger, this function
- * returns a promise that will settle once the pull has completed, and thus
- * can be used in interactive operations that indicate activity to the user.
- *
- * See also: [Note: Full remote pull vs files pull]
- */
onRemoteFilesPull?: () => Promise<void>;
- /**
- * Called when the user performs an action which does not otherwise have any
- * immediate visual impact, to acknowledge it.
- *
- * See: [Note: Visual feedback to acknowledge user actions]
- */
onVisualFeedback: () => void;
- /**
- * Called when the favorite status of given {@link file} should be toggled
- * from its current value.
- *
- * The favorite toggle button is shown only if all three of
- * {@link favoriteFileIDs}, {@link pendingFavoriteUpdates} and
- * {@link onToggleFavorite} are provided.
- */
onToggleFavorite?: (file: EnteFile) => Promise<void>;
- /**
- * Called when {@link visibility} of the given {@link file} should be
- * updated (when the user activates toggle archived action).
- *
- * The toggle archived action is shown only if both
- * {@link pendingVisibilityUpdates} and {@link onFileVisibilityUpdate} are
- * provided.
- */
onFileVisibilityUpdate?: (
file: EnteFile,
visibility: ItemVisibility,
) => Promise<void>;
- /**
- * Called when the given {@link file} should be downloaded.
- *
- * If this is not provided then the download action will not be shown.
- */
onDownload?: (file: EnteFile) => void;
- /**
- * Called when the given {@link file} should be shared via quick link.
- *
- * If this is not provided then the send link action will not be shown.
- */
onSendLink?: (file: EnteFile) => void;
- /**
- * Called when the given {@link file} should be deleted.
- *
- * If this is not provided then the delete action will not be shown.
- */
onDelete?: (file: EnteFile) => Promise<void>;
- /**
- * Called when the user edits an image in the image editor and asks us to
- * save their edits as a copy.
- *
- * Editing is disabled if this is not provided.
- *
- * See {@link onSaveEditedCopy} in the {@link ImageEditorOverlay} props for
- * documentation about the parameters.
- */
onSaveEditedImageCopy?: ImageEditorOverlayProps["onSaveEditedCopy"];
onAddFileToCollection?: (
file: EnteFile,
sourceCollectionSummaryID?: number,
) => void;
- /**
- * The ID of the currently active collection, if any (e.g., when viewing an album).
- */
activeCollectionID?: number;
- /**
- * If set, overrides whether browser back should be consumed to close the
- * viewer.
- *
- * By default this is disabled.
- */
shouldCloseOnBrowserBack?: boolean;
- /**
- * If `true`, disables closing the viewer with the Escape key.
- */
disableEscapeClose?: boolean;
- /**
- * `true` if comments and reactions are enabled.
- * Defaults to `true`.
- */
enableComment?: boolean;
- /**
- * `true` if the comments and reactions feature is enabled for the user.
- *
- * When `false`, the like and comment buttons will be hidden for logged-in
- * users. Defaults to `true`.
- */
isCommentsFeatureEnabled?: boolean;
} & Pick<
FileInfoProps,
"collectionNameByID" | "onSelectCollection" | "onSelectPerson"
>;
-/**
- * A PhotoSwipe based image, live photo and video viewer.
- */
export const FileViewer: React.FC<FileViewerProps> = ({
open,
onClose,
@@ -426,45 +206,22 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const { onGenericError } = useBaseContext();
const shouldCloseOnBrowserBack = shouldCloseOnBrowserBackOverride ?? false;
- // There are 3 things involved in this dance:
- //
- // 1. Us, "FileViewer". We're a React component.
- // 2. The custom PhotoSwipe wrapper, "FileViewerPhotoSwipe". It is a class.
- // 3. The delegate, "FileViewerPhotoSwipeDelegate".
- //
- // The delegate acts as a bridge between us and (our custom) photoswipe
- // class, to avoid recreating the class each time a "dynamic" prop changes.
- // The delegate has a stable identity, we just keep updating the callback
- // functions that it holds.
- //
- // The word "dynamic" here means a prop on whose change we should not
- // recreate the photoswipe dialog.
+ // Keep this identity stable so dynamic props do not recreate PhotoSwipe.
const delegateRef = useRef<
FileViewerPhotoSwipeDelegate<FileViewerAnnotatedFile> | undefined
>(undefined);
- // We also need to maintain a ref to the currently displayed dialog since we
- // might need to ask it to refresh its contents.
const psRef = useRef<
FileViewerPhotoSwipe<FileViewerAnnotatedFile> | undefined
>(undefined);
const handleCloseRef = useRef<() => void>(() => undefined);
const browserBackStateRef = useRef<string | undefined>(undefined);
- // Whenever we get a callback from our custom PhotoSwipe instance, we also
- // get the active file on which that action was performed as an argument. We
- // save it as the `activeAnnotatedFile` state so that the rest of our React
- // tree can use it.
- //
- // This is not guaranteed, or even intended, to be in sync with the active
- // file shown within the file viewer. All that this guarantees is this will
- // refer to the file on which the last user initiated action was performed.
+ // This is the file from the last PhotoSwipe callback, not necessarily its current slide.
const [activeAnnotatedFile, setActiveAnnotatedFile] = useState<
FileViewerAnnotatedFile | undefined
>(undefined);
- // With semantics similar to `activeAnnotatedFile`, this is the exif data
- // associated with the `activeAnnotatedFile`, if any.
const [activeFileExif, setActiveFileExif] = useState<
FileInfoExif | undefined
>(undefined);
@@ -496,55 +253,42 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const [isFullscreen, setIsFullscreen] = useState(false);
- // Map of file ID to map of collection ID to array of comments.
- // For gallery view, we fetch comments from all collections.
- // For collection view, we only fetch comments from that collection.
const [fileComments, setFileComments] = useState<
Map<number, Map<number, Comment[]>>
>(new Map());
- // Map of file ID to map of collection ID to array of all reactions.
- // Includes both file reactions and comment reactions.
const [allReactions, setAllReactions] = useState<
Map<number, Map<number, UnifiedReaction[]>>
>(new Map());
- // Map of user ID to email for displaying reaction/comment authors.
- // Built from collection owner and sharees when fetching social data.
const [userIDToEmail, setUserIDToEmail] = useState<Map<number, string>>(
new Map(),
);
- // Map of anon user ID to decrypted user name for anonymous users.
const [anonUserNames, setAnonUserNames] = useState<Map<string, string>>(
new Map(),
);
- // Ref for fileComments to use in callbacks
const fileCommentsRef = useRef(fileComments);
useEffect(() => {
fileCommentsRef.current = fileComments;
}, [fileComments]);
- // Ref for allReactions to use in callbacks
const allReactionsRef = useRef(allReactions);
useEffect(() => {
allReactionsRef.current = allReactions;
}, [allReactions]);
- // Ref for collectionSummaries to use in callbacks without causing recreations
const collectionSummariesRef = useRef(collectionSummaries);
useEffect(() => {
collectionSummariesRef.current = collectionSummaries;
}, [collectionSummaries]);
- // Ref for fileNormalCollectionIDs to use in callbacks without causing recreations
const fileNormalCollectionIDsRef = useRef(fileNormalCollectionIDs);
useEffect(() => {
fileNormalCollectionIDsRef.current = fileNormalCollectionIDs;
}, [fileNormalCollectionIDs]);
- // Cache for collection keys to avoid refetching during polling
const collectionCacheRef = useRef<
Map<
number,
@@ -558,10 +302,8 @@ export const FileViewer: React.FC<FileViewerProps> = ({
>
>(new Map());
- // Track whether we've already opened the initial sidebar for this open
const hasOpenedInitialSidebarRef = useRef(false);
- // Open the initial sidebar when the file viewer opens with initialSidebar set
useEffect(() => {
if (open && initialSidebar && !hasOpenedInitialSidebarRef.current) {
hasOpenedInitialSidebarRef.current = true;
@@ -571,13 +313,11 @@ export const FileViewer: React.FC<FileViewerProps> = ({
setOpenLikes(true);
}
}
- // Reset the flag when the viewer closes
if (!open) {
hasOpenedInitialSidebarRef.current = false;
}
}, [open, initialSidebar]);
- // Helper to get current user's file reactions from allReactions
const getUserFileReactions = useCallback(
(fileId: number): { collectionId: number; reactionId: string }[] => {
if (!user?.id) return [];
@@ -610,7 +350,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[user?.id],
);
- // If `true`, then we need to trigger a pull from remote when we close.
const [, setNeedsRemotePull] = useState(false);
const handleNeedsRemotePull = useCallback(
@@ -629,8 +368,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
setOpenComments(false);
setOpenLikes(false);
setOpenLikeAlbumSelector(false);
- // No need to `resetMoreMenuButtonOnMenuClose` since we're closing
- // anyway and it'll be removed from the DOM.
setMoreMenuAnchorEl(null);
setOpenImageEditor(false);
setOpenConfirmDelete(false);
@@ -639,8 +376,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
onClose();
}, [onTriggerRemotePull, onClose]);
- // Keep the latest close callback available to non-react event handlers
- // without forcing effects that register handlers to re-run.
handleCloseRef.current = handleClose;
const handleViewInfo = useCallback(
@@ -666,7 +401,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const handleCommentsClose = useCallback(() => setOpenComments(false), []);
- // Handle a new comment being added
const handleCommentAdded = useCallback((comment: Comment) => {
const fileID = comment.fileID;
if (!fileID) return;
@@ -687,7 +421,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
});
}, []);
- // Handle a comment being deleted
const handleCommentDeleted = useCallback(
(collectionID: number, commentID: string) => {
const fileID = activeAnnotatedFile?.file.id;
@@ -714,7 +447,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[activeAnnotatedFile],
);
- // Handle a comment reaction being added
const handleCommentReactionAdded = useCallback(
(reaction: UnifiedReaction) => {
const fileID = activeAnnotatedFile?.file.id;
@@ -738,7 +470,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[activeAnnotatedFile],
);
- // Handle a comment reaction being deleted
const handleCommentReactionDeleted = useCallback(
(collectionID: number, reactionID: string) => {
const fileID = activeAnnotatedFile?.file.id;
@@ -767,14 +498,9 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const handleLikesClose = useCallback(() => setOpenLikes(false), []);
- // Refs to access current state without causing re-renders
- // when used in callbacks that are dependencies of the PhotoSwipe effect.
const activeAnnotatedFileRef = useRef(activeAnnotatedFile);
activeAnnotatedFileRef.current = activeAnnotatedFile;
- // Called when the like button (heart) is clicked.
- // - If gallery view: show album selector (like) OR unlike selector/direct delete
- // - If collection view: toggle like in that collection
const handleLikeClick = useCallback(() => {
if (!user?.id) {
return;
@@ -788,7 +514,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const isGalleryView = !activeCollectionID || activeCollectionID === 0;
if (isGalleryView) {
- // Gallery view - only consider shared collections
const allCollectionIDs =
fileNormalCollectionIDsRef.current?.get(fileId) ?? [];
const collectionIDs = allCollectionIDs.filter((id) =>
@@ -798,9 +523,7 @@ export const FileViewer: React.FC<FileViewerProps> = ({
);
if (reactions.length === 0) {
- // Not liked in any collection
if (collectionIDs.length === 1) {
- // Single album - like directly without showing modal
const collectionId = collectionIDs[0]!;
void (async () => {
try {
@@ -841,11 +564,9 @@ export const FileViewer: React.FC<FileViewerProps> = ({
}
})();
} else {
- // Multiple albums - show album selector
setOpenLikeAlbumSelector(true);
}
} else {
- // Liked in one or more collections - unlike from all
void (async () => {
try {
const deletedReactionIds = new Set<string>();
@@ -880,13 +601,11 @@ export const FileViewer: React.FC<FileViewerProps> = ({
})();
}
} else {
- // Collection view - toggle like in this specific collection
const existingReaction = reactions.find(
(r) => r.collectionId === activeCollectionID,
);
if (existingReaction) {
- // Already liked in this collection - delete
void (async () => {
try {
await deleteReaction(existingReaction.reactionId);
@@ -914,7 +633,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
}
})();
} else {
- // Not liked in this collection - add
void (async () => {
try {
const collection =
@@ -970,7 +688,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const fileId = file.id;
if (isCurrentlyLiked) {
- // Unlike - delete the reaction
const reactions = getUserFileReactions(fileId);
const reactionToDelete = reactions.find(
(r) => r.collectionId === albumId,
@@ -1007,7 +724,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
})();
}
} else {
- // Like - add a reaction
void (async () => {
try {
const collection = await getCollectionByID(albumId);
@@ -1046,7 +762,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
}
})();
}
- // Don't close - user might want to toggle more albums
},
[getUserFileReactions, user?.id],
);
@@ -1062,7 +777,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
existingReactions.map((r) => r.collectionId),
);
- // Filter to only shared collections not already liked
const collectionsToLike = collectionIDs.filter(
(id) =>
!likedCollectionIDs.has(id) &&
@@ -1122,8 +836,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
collectionSummaries,
]);
- // Callback invoked when the download action is triggered by activating the
- // download button in the PhotoSwipe bar.
const handleDownloadBarAction = useCallback(
(annotatedFile: FileViewerAnnotatedFile) => {
onDownload!(annotatedFile.file);
@@ -1131,19 +843,11 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[onDownload],
);
- // Callback invoked when the download action is triggered by activating the
- // download menu item in the more menu.
- //
- // Not memoized since it uses the frequently changing `activeAnnotatedFile`.
const handleDownloadMenuAction = () => {
handleMoreMenuCloseIfNeeded();
onDownload!(activeAnnotatedFile!.file);
};
- // Callback invoked when the send link action is triggered by activating the
- // send link menu item in the more menu.
- //
- // Not memoized since it uses the frequently changing `activeAnnotatedFile`.
const handleSendLinkMenuAction = () => {
handleMoreMenuCloseIfNeeded();
onSendLink!(activeAnnotatedFile!.file);
@@ -1175,22 +879,18 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[],
);
- // Not memoized since it uses the frequently changing `activeAnnotatedFile`.
const handleDelete = async () => {
const file = activeAnnotatedFile!.file;
await onDelete!(file);
handleNeedsRemotePull();
};
- // Not memoized since it uses the frequently changing `activeAnnotatedFile`.
const handleCopyImage = useCallback(() => {
handleMoreMenuCloseIfNeeded();
if (!activeAnnotatedFile) return;
const { imageURL } = activeAnnotatedFile.itemData;
if (!imageURL) return;
- // Safari does not copy if we do not call `navigator.clipboard.write`
- // synchronously within the click event handler, but it does supports
- // passing a promise in lieu of the blob.
+ // Safari requires clipboard.write to run synchronously in the click handler.
void window.navigator.clipboard
.write([
new ClipboardItem({
@@ -1284,11 +984,8 @@ export const FileViewer: React.FC<FileViewerProps> = ({
if (disableDownload) return undefined;
if (!onDownload) return undefined;
if (haveUser) {
- // Logged in users see the download option in the more menu.
return "menu";
} else {
- // Guest viewers show download in the bar buttons, in lieu
- // of the favorite option.
return "bar";
}
})();
@@ -1351,13 +1048,10 @@ export const FileViewer: React.FC<FileViewerProps> = ({
: undefined;
}, [onSelectPerson, handleClose]);
- // Determine if social buttons (like, comment) should be shown.
const showSocialButtons = useMemo(() => {
if (!haveUser) return false;
if (!enableComment) return false;
- // For logged-in users, check if the comments feature is enabled.
if (!isCommentsFeatureEnabled) return false;
- // In collection view: check if that specific collection is shared.
if (
activeCollectionID &&
activeCollectionID !== 0 &&
@@ -1376,7 +1070,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
collectionSummaries,
]);
- // Check if a file belongs to any shared collection (for gallery view).
const isFileInSharedCollection = useCallback(
(fileID: number): boolean => {
if (!collectionSummaries || !fileNormalCollectionIDs) return false;
@@ -1389,17 +1082,9 @@ export const FileViewer: React.FC<FileViewerProps> = ({
[collectionSummaries, fileNormalCollectionIDs],
);
- // Delegate callback to check if social buttons should be shown for a file.
const shouldShowSocialButtons_ = useCallback(
({ file }: FileViewerAnnotatedFile): boolean => {
- // If showSocialButtons is already true in collection view, this
- // won't be called. This callback is only for gallery view where we
- // need to check per-file.
if (!isCommentsFeatureEnabled) return false;
- //
- // If we're in a specific collection context (not gallery view),
- // return false - the collection's shared status is what matters,
- // not whether the file happens to be in some other shared album.
const isGalleryView =
!activeCollectionID || activeCollectionID === 0;
if (!isGalleryView) return false;
@@ -1413,13 +1098,11 @@ export const FileViewer: React.FC<FileViewerProps> = ({
],
);
- // Compute shared albums the file belongs to and which are liked for the modal
const { allAlbumsForFile, likedAlbumIDs } = useMemo(() => {
const file = activeAnnotatedFile?.file;
if (!file)
return { allAlbumsForFile: [], likedAlbumIDs: new Set<number>() };
- // Get all collections the file belongs to, filtered to only shared ones
const collectionIDs = fileNormalCollectionIDs?.get(file.id) ?? [];
const allAlbumsForFile = collectionIDs
.filter((id) =>
@@ -1430,7 +1113,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
name: collectionNameByID?.get(id) ?? `Album ${id}`,
}));
- // Get the set of liked album IDs from allReactions
const fileReactionsMap = allReactions.get(file.id);
const likedAlbumIDs = new Set<number>();
@@ -1493,7 +1175,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const fileReactionsMap = allReactions.get(file.id);
if (!fileReactionsMap) return false;
- // Check if user has liked this file in any collection
for (const reactions of fileReactionsMap.values()) {
const hasUserLike = reactions.some((r) => {
if (r.commentID || r.reactionType !== "green_heart")
@@ -1515,7 +1196,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const isGalleryView =
!activeCollectionID || activeCollectionID === 0;
if (isGalleryView) {
- // Return the count from the collection with most comments
let maxCount = 0;
for (const comments of commentsMap.values()) {
const count = comments.filter((c) => !c.isDeleted).length;
@@ -1523,7 +1203,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
}
return maxCount;
} else {
- // Return count from the active collection
const comments = commentsMap.get(activeCollectionID);
return comments?.filter((c) => !c.isDeleted).length ?? 0;
}
@@ -1553,7 +1232,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const shouldIgnoreKeyboardEvent = useCallback(
(event: KeyboardEvent) => {
- // Allow the file info drawer itself to pass through the slide shortcut.
const shouldAllowFileInfoArrowNavigation =
openFileInfo &&
!fileInfoNavigationLocked &&
@@ -1563,7 +1241,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
event.altKey &&
(event.key == "ArrowLeft" || event.key == "ArrowRight");
- // Don't handle keydowns if any of the viewer's own modals are open.
if (
(openFileInfo && !shouldAllowFileInfoArrowNavigation) ||
openComments ||
@@ -1577,8 +1254,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
return true;
}
- // Also ignore keydowns if keyboard focus is inside an editable field
- // (e.g., when the CollectionSelector dialog's search TextField is focused)
const activeElement = document.activeElement as HTMLElement | null;
if (activeElement) {
const tagName = activeElement.tagName;
@@ -1677,10 +1352,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
break;
case "toggle-archive":
if (!isPendingToggleArchive) {
- // Provide extra visual feedback when the toggle archive
- // action is invoked via a keyboard shortcut since there
- // is no corresponding screen control visible (the more
- // menu might not be visible).
onVisualFeedback();
toggleArchived?.();
}
@@ -1709,7 +1380,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
],
);
- // Initial value of delegate.
if (!delegateRef.current) {
delegateRef.current = {
getFiles,
@@ -1724,7 +1394,7 @@ export const FileViewer: React.FC<FileViewerProps> = ({
};
}
- // Updates to delegate callbacks.
+ // Updating callbacks in place preserves the current zoom and pan state.
useEffect(() => {
const delegate = delegateRef.current!;
delegate.getFiles = getFiles;
@@ -1748,50 +1418,31 @@ export const FileViewer: React.FC<FileViewerProps> = ({
performKeyAction,
]);
- // Handle updates to files.
- //
- // See: [Note: Updates to the files prop for FileViewer]
useEffect(() => {
if (!files.length) {
- // If there are no more files left, close the viewer.
handleClose();
} else if (open && activeAnnotatedFile) {
- // Only refresh if the viewer is still open and we have an active file.
- // This prevents race conditions when navigating away (e.g., when clicking
- // the navigate button in AlbumAddedNotification while the viewer is open).
+ // PhotoSwipe has no valid current-slide state before annotation completes.
psRef.current?.refreshSlideOnFilesUpdateIfNeeded();
}
}, [handleClose, files, open, activeAnnotatedFile]);
useEffect(() => {
- // This effect might get triggered when the none of the files that were
- // being shown are eligible to be shown anymore. e.g. suppose we are the
- // archiveItems pseudo-collection, and the only archived file there is
- // marked as unarchived by the user within the file viewer.
- //
- // In such cases, don't attempt to refresh since that causes various
- // invariants (like the existence of a "currentFile") to get broken
- // inside the `FileViewerPhotoSwipe` implementation.
if (open && files.length) {
psRef.current?.refreshCurrentSlideFavoriteButtonIfNeeded();
}
}, [favoriteFileIDs, pendingFavoriteUpdates, files, open]);
- // Refresh like button when allReactions changes.
useEffect(() => {
if (open && files.length) {
psRef.current?.refreshCurrentSlideLikeButtonIfNeeded();
}
}, [allReactions, files, open]);
- // Fetch comments and reactions for the current file (only for shared albums).
const activeFileID = activeAnnotatedFile?.file.id;
useEffect(() => {
if (!open || !activeFileID) return;
- // Only fetch social data if social buttons should be shown.
- // In collection view, use showSocialButtons (based on that collection).
- // In gallery view, check if the file is in any shared collection.
const isGalleryView = !activeCollectionID || activeCollectionID === 0;
const shouldFetch =
showSocialButtons ||
@@ -1816,7 +1467,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const collection =
await getCollectionByID(collectionId);
- // Cache collection data for polling refresh
collectionCacheRef.current.set(collectionId, {
key: collection.key,
ownerID: collection.owner.id,
@@ -1828,7 +1478,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
hasPublicURLs: collection.publicURLs.length > 0,
});
- // Build user ID to email map from collection owner and sharees
if (collection.owner.email) {
newUserIDToEmail.set(
collection.owner.id,
@@ -1851,7 +1500,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
commentsMap.set(collectionId, comments);
reactionsMap.set(collectionId, reactions);
- // Fetch anonymous user profiles only if collection has public links
if (collection.publicURLs.length > 0) {
try {
const anonProfiles = await getAnonProfiles(
@@ -1924,17 +1572,14 @@ export const FileViewer: React.FC<FileViewerProps> = ({
isCommentsFeatureEnabled,
]);
- // Refresh comment count when fileComments changes.
useEffect(() => {
if (open && files.length) {
psRef.current?.refreshCurrentSlideCommentCountIfNeeded();
}
}, [fileComments, files, open]);
- // Polling interval for refreshing social data (5 seconds)
const SOCIAL_REFRESH_INTERVAL_MS = 5_000;
- // Refresh social data for logged-in users (uses cached collection keys)
const refreshSocialData = useCallback(async () => {
if (!activeFileID) return;
@@ -1956,9 +1601,8 @@ export const FileViewer: React.FC<FileViewerProps> = ({
: [activeCollectionID];
for (const collectionId of collectionIDs) {
- // Use cached collection data (populated during initial fetch)
const cached = collectionCacheRef.current.get(collectionId);
- if (!cached) continue; // Skip if not in cache
+ if (!cached) continue;
try {
const { comments, reactions } = await getUnifiedSocialDiff(
@@ -2019,7 +1663,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
isCommentsFeatureEnabled,
]);
- // Poll for social data when comments or likes sidebar is open.
useInterval(
refreshSocialData,
openComments || openLikes ? SOCIAL_REFRESH_INTERVAL_MS : null,
@@ -2027,7 +1670,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
useEffect(() => {
if (open) {
- // We're open. Create psRef. This will show the file viewer dialog.
log.debug(() => "Opening file viewer");
const pswp = new FileViewerPhotoSwipe({
@@ -2053,23 +1695,15 @@ export const FileViewer: React.FC<FileViewerProps> = ({
psRef.current = pswp;
return () => {
- // Close dialog in the effect callback.
log.debug(() => "Closing file viewer");
pswp.closeIfNeeded();
};
} else {
return undefined;
}
- // Be careful with adding new dependencies here, or changing the source
- // of existing ones. If any of these dependencies change unnecessarily,
- // then the file viewer will start getting reloaded even when it is
- // already open.
- //
- // Note: showSocialButtons and enableComment are intentionally NOT included
- // here even though they're passed to the constructor. The delegate's
- // shouldShowSocialButtons handles dynamic visibility, and these values only
- // change based on collectionSummaries which we don't want to trigger a full
- // recreation.
+ // Recreating PhotoSwipe discards the open viewer's state.
+ // Social visibility changes through delegate callbacks.
+ // It must not enter this dependency list.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [
open,
@@ -2093,8 +1727,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
useEffect(() => {
if (!open || !shouldCloseOnBrowserBack) return;
- // Consume one browser-back action to close the viewer overlay instead
- // of navigating away immediately.
const stateMarker = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
browserBackStateRef.current = stateMarker;
@@ -2128,9 +1760,7 @@ export const FileViewer: React.FC<FileViewerProps> = ({
const handleFileMetadataUpdate = useMemo(() => {
return onRemoteFilesPull
? async () => {
- // Wait for the files pull to complete.
await onRemoteFilesPull();
- // Set the flag to trigger the full pull later.
handleNeedsRemotePull();
}
: undefined;
@@ -2270,7 +1900,6 @@ export const FileViewer: React.FC<FileViewerProps> = ({
<MoreMenuItemTitle>
{t("copy_as_png")}
</MoreMenuItemTitle>
- {/* Tweak icon size to visually fit better with neighbours */}
<ContentCopyIcon sx={{ "&&": { fontSize: "18px" } }} />
</MoreMenuItem>
)}
@@ -2284,11 +1913,7 @@ export const FileViewer: React.FC<FileViewerProps> = ({
<MoreMenuItem
onClick={handleToggleFullscreen}
divider
- sx={{
- borderColor: "fixed.dark.divider",
- /* 12px + 2px */
- pb: "14px",
- }}
+ sx={{ borderColor: "fixed.dark.divider", pb: "14px" }}
>
<MoreMenuItemTitle>
{isFullscreen
@@ -2344,10 +1969,6 @@ const MoreMenuItem = styled(MenuItem)(
({ theme }) => `
min-width: 210px;
- /* MUI MenuItem default implementation has a minHeight of "48px" below the
- "sm" breakpoint, and auto after it. We always want the same height, so
- set minHeight auto and use an explicit padding always to come out to 44px
- (20px (icon or Typography height + 12 + 12) */
padding-block: 12px;
min-height: auto;
@@ -2355,7 +1976,6 @@ const MoreMenuItem = styled(MenuItem)(
justify-content: space-between;
align-items: center;
- /* Same as other controls on the PhotoSwipe UI */
color: rgba(255 255 255 / 0.85);
&:hover {
color: rgba(255 255 255 / 1);
@@ -2373,22 +1993,9 @@ const MoreMenuItemTitle: React.FC<React.PropsWithChildren> = ({ children }) => (
);
type ConfirmDeleteFileDialogProps = ModalVisibilityProps & {
- /**
- * Called when the user confirms the deletion.
- *
- * The delete button will show an activity indicator until this async
- * operation completes.
- */
onConfirm: () => Promise<void>;
};
-/**
- * A bespoke variant of AttributedMiniDialog for use by the delete file
- * confirmation prompt that we show in the file viewer.
- *
- * - It auto focuses the primary action.
- * - It uses a lighter backdrop in light mode.
- */
const ConfirmDeleteFileDialog: React.FC<ConfirmDeleteFileDialogProps> = ({
open,
onClose,
@@ -2413,7 +2020,6 @@ const ConfirmDeleteFileDialog: React.FC<ConfirmDeleteFileDialogProps> = ({
};
const handleClose: ModalProps["onClose"] = (_, reason) => {
- // Ignore backdrop clicks when we're processing the user request.
if (reason == "backdropClick" && phase == "loading") return;
resetPhaseAndClose();
};
@@ -2424,7 +2030,6 @@ const ConfirmDeleteFileDialog: React.FC<ConfirmDeleteFileDialogProps> = ({
onClose={handleClose}
title={t("trash_file_title")}
sx={(theme) => ({
- // See: [Note: Lighter backdrop for overlays on photo viewer]
...theme.applyStyles("light", {
".MuiBackdrop-root": {
backgroundColor: theme.vars.palette.backdrop.faint,
@@ -2460,12 +2065,7 @@ const ConfirmDeleteFileDialog: React.FC<ConfirmDeleteFileDialogProps> = ({
};
type ShortcutsProps = ModalVisibilityProps &
- Pick<FileViewerProps, "disableDownload"> & {
- /**
- * `true` if we're running in a context where there is a logged in user.
- */
- haveUser: boolean;
- };
+ Pick<FileViewerProps, "disableDownload"> & { haveUser: boolean };
const Shortcuts: React.FC<ShortcutsProps> = ({
open,
@@ -2577,27 +2177,18 @@ const Shortcut: React.FC<ShortcutProps> = ({ action, shortcut }) => (
);
const fileIsEditableImage = (file: EnteFile) => {
- // Only images are editable.
if (file.metadata.fileType !== FileType.image) return false;
const extension = lowercaseExtension(fileFileName(file));
- // Assume it is editable;
let isRenderable = true;
if (extension && needsJPEGConversion(extension)) {
- // See if the file is on the whitelist of extensions that we know
- // will not be directly renderable.
if (!isDesktop) {
- // On the web, we only support HEIC conversion.
isRenderable = isHEICExtension(extension);
}
}
return isRenderable;
};
-/**
- * Return a promise that resolves with a "image/png" blob derived from the given
- * {@link imageURL} that can be written to the navigator's clipboard.
- */
const createImagePNGBlob = async (imageURL: string): Promise<Blob> =>
new Promise((resolve, reject) => {
const image = new Image();
diff --git a/web/packages/gallery/components/viewer/data-source-core.ts b/web/packages/gallery/components/viewer/data-source-core.ts
index 5e1cfdef93..2344ea8b35 100644
--- a/web/packages/gallery/components/viewer/data-source-core.ts
+++ b/web/packages/gallery/components/viewer/data-source-core.ts
@@ -7,145 +7,25 @@ import type { ParsedMetadata } from "ente-media/file-metadata";
import { FileType } from "ente-media/file-type";
import { ensureString } from "ente-utils/ensure";
-/**
- * This is a subset of the fields expected by PhotoSwipe itself (see the
- * {@link SlideData} type exported by PhotoSwipe).
- */
interface PhotoSwipeSlideData {
- /**
- * The image URL expected by PhotoSwipe.
- *
- * This is set to the URL of the image that should be shown in the image
- * viewer component provided by PhotoSwipe.
- *
- * It will be a renderable (i.e., possibly converted) object URL obtained
- * from the current "best" image we have.
- *
- * For example, if all we have is the thumbnail, then this'll be an
- * renderable object URL obtained from the thumbnail data. Then later when
- * we fetch the original image, this'll be the renderable object URL derived
- * from the original. But if it is a video, this will just be cleared.
- */
src?: string | undefined;
- /**
- * The width (in pixels) of the {@link src} image.
- */
width?: number | undefined;
- /**
- * The height (in pixels) of the {@link src} image.
- */
height?: number | undefined;
- /**
- * The alt text associated with the file.
- *
- * This will be set to the file's caption. PhotoSwipe will use it as the alt
- * text when constructing img elements (if any) for this item. We will also
- * use this for displaying the visible "caption" element atop the file (both
- * images and video).
- */
alt?: string;
- /**
- * The HTML (string) contents of the slide, if we don't wish for it to show
- * an image.
- */
html?: string | undefined;
}
-/**
- * The data returned by the flagship {@link itemDataForFile} function provided
- * by the file viewer data source module.
- *
- * This is the minimal data expected by PhotoSwipe, plus some fields we use
- * ourselves in the custom scaffolding we have around PhotoSwipe.
- */
export type ItemData = PhotoSwipeSlideData & {
- /**
- * The ID of the {@link EnteFile} whose data we are.
- */
fileID: number;
- /**
- * The {@link EnteFile} type of the file whose data we are.
- *
- * Expected to be one of {@link FileType}.
- */
fileType: number;
- /**
- * The renderable object URL of the image associated with the file.
- *
- * - For images, this will be the object URL of a renderable image.
- * - For videos, this will not be defined.
- * - For live photos, this will be a renderable object URL of the image
- * portion of the live photo.
- */
imageURL?: string;
- /**
- * The original image associated with the file, as a Blob.
- *
- * - For images, this will be the original image itself.
- * - For live photos, this will be the image component of the live photo.
- * - For videos, this will be not be present.
- */
originalImageBlob?: Blob;
- /**
- * The renderable object URL of the video associated with the file.
- *
- * - For images, this will not be defined.
- * - For videos, this will be the object URL of a renderable video (but only
- * if {@link videoPlaylistURL} is not set).
- * - For live photos, this will be a renderable object URL of the video
- * portion of the live photo.
- */
videoURL?: string;
- /**
- * The object URL to an HLS playlist that can be used to play the video
- * associated with the file in a streaming manner.
- *
- * This will only be defined for videos for which a corresponding streamable
- * version has been created.
- *
- * Only one of {@link videoURL} or {@link videoPlaylistURL} will be set at a
- * time.
- */
videoPlaylistURL?: string;
- /**
- * The DOM element ID of the `media-controller` element that is showing the
- * video for the current item.
- *
- * If present, this value will be used to display controls for controlling
- * the video wrapped by the media-controller.
- *
- * This is only set for videos that are streamed using HLS (i.e. videos for
- * which {@link videoPlaylistURL} has also been set).
- */
mediaControllerID?: string;
- /**
- * `true` if we should indicate to the user that we're still fetching data
- * for this file.
- *
- * Note that this doesn't imply that the data is final. e.g. for a live
- * photo, this will be not be set after we get the original image component,
- * but the fetch for the video component might still be ongoing.
- */
isContentLoading?: boolean;
- /**
- * This will be explicitly set to `false` when we want to disable
- * PhotoSwipe's built in image zoom.
- *
- * It is set while the thumbnail is loaded.
- */
isContentZoomable?: boolean;
- /**
- * This will be `true` if the fetch for the file's data has failed.
- *
- * It is possible for this to be set in tandem with the content URLs also
- * being set (e.g. if we were able to use the cached thumbnail, but the
- * original file could not be fetched because of an network error).
- */
fetchFailed?: boolean;
- /**
- * This will be `true` if the item data for this particular file is
- * considered transient, and should not be cached.
- */
isTransient?: boolean;
};
@@ -162,9 +42,6 @@ export interface HLSPlaylistData {
export type HLSPlaylistDataForFile = HLSPlaylistData | "skip" | undefined;
-/**
- * Options to modify the default behaviour of {@link itemDataForFile}.
- */
export interface ItemDataOpts {
videoQuality?: "auto" | "original";
}
@@ -207,59 +84,17 @@ export interface FileViewerDataSource {
forgetExif: () => void;
}
-/**
- * This module stores and serves data required by our custom PhotoSwipe
- * instance, effectively acting as an in-memory cache.
- *
- * By keeping this independent of the lifetime of the PhotoSwipe instance, we
- * can reuse the same cache for multiple displays of our file viewer.
- *
- * This will be cleared on logout.
- */
class FileViewerDataSourceState {
- /**
- * Non-zero if a file viewer is currently open.
- *
- * This is a counter, but the file viewer data source has other many
- * assumptions about only a single instance of PhotoSwipe being active at a
- * time, so this could've been a boolean as well.
- */
+ // Other viewer code assumes at most one active PhotoSwipe instance.
viewerCount = 0;
- /**
- * True if our state needs to be cleared the next time the file viewer is
- * closed.
- */
needsReset = false;
- /**
- * The best data we have for a particular file (ID).
- */
itemDataByFileID = new Map<number, ItemData>();
- /**
- * The validity (if applicable) for the corresponding entry in
- * {@link itemDataByFileID}.
- */
itemDataValidTillByFileID = new Map<number, Date>();
- /**
- * The latest callback registered for notifications of better data being
- * available for a particular file (ID).
- */
needsRefreshByFileID = new Map<number, () => void>();
- /**
- * The exif data we have for a particular file (ID).
- */
fileInfoExifByFileID = new Map<number, FileInfoExif>();
- /**
- * The latest callback registered for notifications of exif data being
- * available for a particular file (ID).
- */
exifObserverByFileID = new Map<number, (exif: FileInfoExif) => void>();
}
-/**
- * State shared by functions in this module.
- *
- * See {@link FileViewerDataSourceState}.
- */
export const createFileViewerDataSource = ({
downloadManager,
hlsPlaylistDataForFile,
@@ -272,26 +107,9 @@ export const createFileViewerDataSource = ({
_state = new FileViewerDataSourceState();
};
- /**
- * Clear any internal state maintained by the file viewer data source.
- */
const logoutFileViewerDataSource = resetState;
- /**
- * Clear any internal state if possible. This is invoked when files have been
- * updated on remote, and those changes synced locally.
- *
- * Because we also retain callbacks, clearing existing item data when the file
- * viewer is open can lead to problematic edge cases. Thus, this function
- * behaves in two different ways:
- *
- * - If the file viewer is already open, then we enqueue a reset for when it is
- * closed the next time.
- *
- * - Otherwise we immediately reset our state.
- *
- * See: [Note: Changes to underlying files when file viewer is open]
- */
+ // Live callbacks make an immediate reset unsafe while the viewer is open.
const resetFileViewerDataSourceOnClose = () => {
if (_state.viewerCount) {
_state.needsReset = true;
@@ -300,81 +118,20 @@ export const createFileViewerDataSource = ({
}
};
- /**
- * Called by the file viewer whenever it is opened.
- */
const fileViewerWillOpen = () => {
_state.viewerCount++;
};
- /**
- * Called by the file viewer whenever it has been closed.
- */
const fileViewerDidClose = () => {
_state.viewerCount--;
if (_state.needsReset && _state.viewerCount == 0) {
- // Reset everything.
resetState();
} else {
- // Selectively clear.
forgetFailedOrTransientItems();
forgetExif();
}
};
- /**
- * Return the best available {@link ItemData} for rendering the given
- * {@link file}.
- *
- * If an entry does not exist for a particular file, then it is lazily added on
- * demand, and updated as we keep getting better data (thumbnail, original) for
- * the file.
- *
- * At each step, we call the provided callback so that file viewer can call us
- * again to get the updated data.
- *
- * @param opts Options to modify the default behaviours.
- *
- * ---
- *
- * Detailed flow:
- *
- * If we already have the final data about the file, then this function will
- * return it and do nothing subsequently.
- *
- * Otherwise, it will:
- *
- * 1. Return empty slide data; PhotoSwipe will not show anything in the image
- * area but will otherwise render UI controls properly (in most cases a
- * cached renderable thumbnail URL will be available shortly).
- *
- * 2. Insert this empty data in its cache so that we don't enqueue multiple
- * updates.
- *
- * Then it we start fetching data for the file.
- *
- * First it'll fetch the thumbnail. Once that is done, it'll update the data it
- * has cached, and notify the caller (using the provided callback) so it can
- * refresh the slide.
- *
- * Then it'll continue fetching the original.
- *
- * - For images this will be the single original.
- *
- * - For videos this will be either the HLS playlist to a streamable variant of
- * the video (if the video has one available), or the original video itself.
- *
- * - For live photos, this will also be a two step process, first fetching the
- * video component, then fetching the image component.
- *
- * At this point, the data for this file will be considered final, and
- * subsequent calls for the same file will return this same value unless it is
- * invalidated.
- *
- * If at any point an error occurs, we reset our cache for this file so that the
- * next time the data is requested we repeat the process instead of continuing
- * to serve the incomplete result.
- */
const itemDataForFile = (
file: EnteFile,
opts: ItemDataOpts | undefined,
@@ -385,14 +142,11 @@ export const createFileViewerDataSource = ({
const validTill = _state.itemDataValidTillByFileID.get(fileID);
if (validTill && validTill < new Date()) {
- // Don't use the cached entry if it has become stale.
forgetItemDataForFileID(fileID);
}
let itemData = _state.itemDataByFileID.get(fileID);
- // We assume that there is only one file viewer that is using us at a given
- // point of time. This assumption is currently valid.
_state.needsRefreshByFileID.set(file.id, needsRefresh);
if (!itemData) {
@@ -404,64 +158,18 @@ export const createFileViewerDataSource = ({
return itemData;
};
- /**
- * Forget item data for the given {@link file}.
- *
- * This is called when we change the options passed to {@link itemDataForFile},
- * and so would like to clear any previously cached data.
- */
const forgetItemDataForFileID = (fileID: number) => {
_state.itemDataByFileID.delete(fileID);
_state.itemDataValidTillByFileID.delete(fileID);
};
- /**
- * Forget item data for the given {@link file} if its fetch had failed, or if it
- * is caching something that is transient in nature.
- *
- * It is called when the user moves away from a slide. In particular, this way
- * we can reset failures, if any, for a slide so that the fetch is tried again
- * when we come back to it.
- *
- * [Note: File viewer preloading and contentDeactivate]
- *
- * Note that because of preloading, this will only have a user visible effect if
- * the user moves out of the preload range. Let's take an example:
- *
- * - User opens slide at index `i`. Then the adjacent slides, `i - 1` and `i +
- * 1`, also get preloaded.
- *
- * - User moves away from `i` (in either direction, but let us take the example
- * if they move `i - 1`).
- *
- * - This function will get called for `i` and will clear any failed or
- * transient state.
- *
- * - But since PhotoSwipe already has the slides ready for `i`, if the user then
- * moves back to `i` then PhotoSwipe will not attempt to recreate the slide
- * and so will not even try to get "itemData". So this will only have an
- * effect if they move out of preload range (e.g. `i - 1`, `i - 2`), and then
- * back (`i - 1`, `i`).
- *
- * See: [Note: File viewer error handling]
- *
- * See: [Note: Caching HLS playlist data]
- */
+ // Adjacent slides stay alive, so retry starts only after leaving preload range.
const forgetItemDataForFileIDIfNeeded = (fileID: number) => {
const itemData = _state.itemDataByFileID.get(fileID);
if (itemData?.fetchFailed || itemData?.isTransient)
forgetItemDataForFileID(fileID);
};
- /**
- * Update the alt attribute of the {@link ItemData}, if any, associated with the
- * given {@link EnteFile}.
- *
- * @param fileID The ID of the file whose {@link alt} attribute we want to
- * update.
- *
- * @param newAlt The new value of the {@link alt} attribute.
- */
const updateItemDataAlt = (fileID: number, newAlt: string) => {
const itemData = _state.itemDataByFileID.get(fileID);
if (itemData) {
@@ -469,14 +177,6 @@ export const createFileViewerDataSource = ({
}
};
- /**
- * Forget item data for the all files whose fetch had failed, or if the
- * corresponding item data is transient and shouldn't be cached.
- *
- * This is called when the user closes the file viewer; in particular, this way
- * we attempt a full retry for previously failed files when the user reopens the
- * viewer the next time.
- */
const forgetFailedOrTransientItems = () =>
[..._state.itemDataByFileID.keys()].forEach(
forgetItemDataForFileIDIfNeeded,
@@ -490,8 +190,6 @@ export const createFileViewerDataSource = ({
const fileType = file.metadata.fileType;
const update = (itemData: Partial<ItemData>, validTill?: Date) => {
- // Use the file's caption as its alt text (in addition to using it as
- // the visible caption).
const alt = file.pubMagicMetadata?.data.caption;
_state.itemDataByFileID.set(file.id, {
@@ -513,11 +211,7 @@ export const createFileViewerDataSource = ({
hlsPlaylistData: HLSPlaylistDataForFile,
) => {
const videoURLD = videoURL ? { videoURL } : {};
- // See: [Note: Caching HLS playlist data]
- //
- // In brief, there are three cases:
if (typeof hlsPlaylistData == "object") {
- // 1. If we have a playlist, we can cache it
const {
playlistURL: videoPlaylistURL,
width,
@@ -528,8 +222,7 @@ export const createFileViewerDataSource = ({
createHLSPlaylistItemDataValidity(),
);
} else {
- // 2. if the file is not eligible ("skip"), we can cache it.
- // 3. Otherwise it's transient and shouldn't be cached indefinitely.
+ // "skip" is stable; undefined may become a playlist later.
update({
...videoURLD,
isTransient: hlsPlaylistData != "skip",
@@ -537,8 +230,6 @@ export const createFileViewerDataSource = ({
}
};
- // Use the last best available data, but stop showing the loading indicator
- // and instead show the error indicator.
const markFailed = () => {
const lastData: Partial<ItemData> =
_state.itemDataByFileID.get(file.id) ?? {};
@@ -549,16 +240,10 @@ export const createFileViewerDataSource = ({
try {
const thumbnailURL =
await downloadManager.renderableThumbnailURL(file);
- // While the types don't reflect it, it is safe to use the ! (null
- // assertion) here since renderableThumbnailURL can throw but will not
- // return undefined by default.
const thumbnailData = await withDimensionsIfPossible(
ensureString(thumbnailURL),
);
- // If the aspect ratio of the original file matches the aspect ratio of
- // the thumbnail, then render the thumbnail using the original's
- // dimensions for a better visual experience.
const { width, height } = thumbnailDimensions(thumbnailData, file);
update({
@@ -569,14 +254,6 @@ export const createFileViewerDataSource = ({
isContentZoomable: false,
});
} catch (e) {
- // If we can't even get the thumbnail, then a network error is likely
- // (download manager already has retries); in particular, it cannot be a
- // format error since thumbnails are already standard JPEGs.
- //
- // Notify the user of the error. The entire process will be retried when
- // they reopen the slide later.
- //
- // See: [Note: File viewer error handling]
log.error("Failed to fetch thumbnail", e);
markFailed();
return;
@@ -589,8 +266,6 @@ export const createFileViewerDataSource = ({
file,
downloadManager.publicAlbumsCredentials,
);
- // We have a HLS playlist, and the user didn't request the original.
- // Early return so that we don't initiate a fetch for the original.
if (
typeof hlsPlaylistData == "object" &&
opts?.videoQuality != "original"
@@ -617,15 +292,7 @@ export const createFileViewerDataSource = ({
}
case "livePhoto": {
- // The image component of a live photo usually is an HEIC file,
- // which cannot be displayed natively by many browsers and needs
- // a conversion, which is slow on web (faster on desktop). We
- // already have both components available since they're part of
- // the same zip. And in the UI, the first (default) interaction
- // is to loop the live video.
- //
- // For these reasons, we resolve with the video first, then
- // resolve with the image.
+ // Resolve video first because the HEIC image conversion is slow.
const videoURL = await sourceURLs.videoURL();
update({
videoURL,
@@ -644,39 +311,11 @@ export const createFileViewerDataSource = ({
}
}
} catch (e) {
- // [Note: File viewer error handling]
- //
- // Generally, file downloads will fail because of two reasons: Network
- // errors, or format errors.
- //
- // In the first case (network error), the `renderableSourceURLs` method
- // above will throw. We will show an error indicator icon in the UI, but
- // will keep showing the thumbnail.
- //
- // In the second case (format error), we'll get back a URL, but if a
- // file conversion was needed but not possible (say, it is an
- // unsupported format), we might have at our hands the original file's
- // untouched URL, that the browser might not know how to render.
- //
- // In this case we won't get into an error state here, but PhotoSwipe
- // will encounter an error when trying to render it, and it will show
- // our customized error message ("This file could not be previewed"),
- // but the user will still be able to download it.
log.error("Failed to fetch file", e);
markFailed();
}
};
- /**
- * Take a image URL, determine its dimensions using browser APIs if possible,
- * and return the URL and its dimensions in a form that can directly be passed
- * to PhotoSwipe as {@link ItemData}.
- *
- * If the dimensions cannot be extracted (i.e., the browser was not able to load
- * the image), then PhotoSwipe itself will also not likely be able to render it,
- * but we still return the {@link imageURL} back so that PhotoSwipe can show the
- * appropriate error when trying to render it.
- */
const withDimensionsIfPossible = (
imageURL: string,
): Promise<Partial<ItemData>> =>
@@ -692,14 +331,6 @@ export const createFileViewerDataSource = ({
image.src = imageURL;
});
- /**
- * Return the dimensions to use for the thumbnail associated with {@link file}.
- *
- * If the aspect ratio of the thumbnail is (approximately) equal to that of the
- * dimensions we have on record for the original image (obtained from the file
- * metadata), then use the dimensions of the original image in lieu of the
- * thumbnail dimensions for a more graceful transition during image loads.
- */
const thumbnailDimensions = (
{ width: thumbnailWidth, height: thumbnailHeight }: Partial<ItemData>,
file: EnteFile,
@@ -715,40 +346,9 @@ export const createFileViewerDataSource = ({
}
return { width: thumbnailWidth, height: thumbnailHeight };
};
- /**
- * Return a new validity for a HLS playlist containing pre-signed URLs.
- *
- * The content chunks in HLS playlist generated by
- * {@link hlsPlaylistDataForFile} use pre-signed URLs generated by remote (see
- * `PreSignedRequestValidityDuration` in the museum source). These have a
- * validity of 7 days. We keep a 2 day buffer, and consider any item data that
- * uses such playlist as stale after 5 days.
- */
+ // Museum's signed playlist URLs last seven days; expire them two days early.
const createHLSPlaylistItemDataValidity = () =>
- new Date(Date.now() + 5 * 24 * 60 * 60 * 1000); /* 5 days */
-
- /**
- * Return the cached Exif data for the given {@link file}.
- *
- * The shape of the returned data is such that it can directly be used by the
- * {@link FileInfo} sidebar.
- *
- * Exif extraction is not too expensive, and takes around 10-200 ms usually, so
- * this can be done preemptively. As soon as we get data for a particular item
- * as the user swipes through the file viewer, we extract its exif data using
- * {@link updateFileInfoExifIfNeeded}.
- *
- * Then if the user were to open the file info sidebar for that particular file,
- * the associated exif data will be returned by this function. Since the happy
- * path is for synchronous use in a React component, this function synchronously
- * returns the cached value (and the callback is never invoked).
- *
- * The user can open the file info sidebar before the original has been fetched,
- * so it is possible that this function gets called before
- * {@link updateFileInfoExifIfNeeded} has completed. In such cases, this
- * function will synchronously return `undefined`, and then later call the
- * provided {@link observer} once the extraction results are available.
- */
+ new Date(Date.now() + 5 * 24 * 60 * 60 * 1000);
const fileInfoExifForFile = (
file: EnteFile,
observer: (exifData: FileInfoExif) => void,
@@ -761,25 +361,9 @@ export const createFileViewerDataSource = ({
return undefined;
};
- /**
- * Update, if needed, the cached Exif data for with the given {@link itemData}.
- *
- * This function is expected to be called when an item is loaded as PhotoSwipe
- * content. It can be safely called multiple times - it will ignore calls until
- * the item has an associated {@link originalImageBlob}, and it will also ignore calls
- * that are made after exif data has already been extracted.
- *
- * If required, it will extract the exif data from the file, massage it to a
- * form suitable for use by {@link FileInfo}, and stash it in its caches, and
- * notify the most recent observer for that file attached via
- * {@link fileInfoExifForFile}.
- *
- * See also {@link forgetExifForItemData}.
- */
const updateFileInfoExifIfNeeded = async (itemData: ItemData) => {
const { fileID, fileType, originalImageBlob } = itemData;
- // We already have it available.
if (_state.fileInfoExifByFileID.has(fileID)) return;
const update = (exifData: FileInfoExif) => {
@@ -787,13 +371,11 @@ export const createFileViewerDataSource = ({
_state.exifObserverByFileID.get(fileID)?.(exifData);
};
- // For videos, insert a placeholder.
if (fileType == FileType.video) {
update(createPlaceholderFileInfoExif());
return;
}
- // This is not a video, but the original image is not available yet.
if (!originalImageBlob) return;
try {
@@ -803,8 +385,6 @@ export const createFileViewerDataSource = ({
update({ tags, parsed });
} catch (e) {
log.error("Failed to extract exif", e);
- // Save the empty placeholder exif corresponding to the file, no point
- // in unnecessarily retrying this, it will deterministically fail again.
update(createPlaceholderFileInfoExif());
}
};
@@ -814,17 +394,11 @@ export const createFileViewerDataSource = ({
parsed: undefined,
});
- /**
- * Clear any cached {@link FileInfoExif} for the given {@link ItemData}.
- */
const forgetExifForItemData = ({ fileID }: ItemData) => {
_state.fileInfoExifByFileID.delete(fileID);
_state.exifObserverByFileID.delete(fileID);
};
- /**
- * Clear all cached {@link FileInfoExif}.
- */
const forgetExif = () => {
_state.fileInfoExifByFileID.clear();
_state.exifObserverByFileID.clear();
diff --git a/web/packages/gallery/components/viewer/photoswipe-core.ts b/web/packages/gallery/components/viewer/photoswipe-core.ts
index 79987486bc..17528d0288 100644
--- a/web/packages/gallery/components/viewer/photoswipe-core.ts
+++ b/web/packages/gallery/components/viewer/photoswipe-core.ts
@@ -44,82 +44,15 @@ export interface FileViewerPhotoSwipeDelegate<
T extends FileViewerPhotoSwipeAnnotatedFile =
FileViewerPhotoSwipeAnnotatedFile,
> {
- /**
- * Called to obtain the latest list of files.
- *
- * [Note: Changes to underlying files when file viewer is open]
- *
- * The list of files shown by the viewer might change while the viewer is
- * open. We do not actively refresh the viewer when this happens since that
- * would result in the user's zoom / pan state being lost.
- *
- * However, we always read the latest list via the delegate, so any
- * subsequent user initiated slide navigation (e.g. moving to the next
- * slide) will use the new list.
- */
getFiles: () => EnteFile[];
- /**
- * Return `true` if the provided file has been marked as a favorite by the
- * user.
- *
- * The toggle favorite button will not be shown for the file if
- * this callback returns `undefined`. Otherwise the return value determines
- * the toggle state of the toggle favorite button for the file.
- */
isFavorite: (annotatedFile: T) => boolean | undefined;
- /**
- * Return `true` if there is an inflight request to update the favorite
- * status of the file.
- */
isFavoritePending: (annotatedFile: T) => boolean;
- /**
- * Called when the user activates the toggle favorite action on a file.
- *
- * The toggle favorite button will be disabled for the file until the
- * promise returned by this function returns fulfills.
- *
- * > Note: The caller is expected to handle any errors that occur, and
- * > should not reject for foreseeable failures, otherwise the button will
- * > remain in the disabled state (until the file viewer is closed).
- */
+ // Handle foreseeable failures here; rejection leaves the button disabled.
toggleFavorite: (annotatedFile: T) => Promise<void>;
- /**
- * Return `true` if the provided file has a green_heart reaction from the
- * current user.
- */
isLiked: (annotatedFile: T) => boolean;
- /**
- * Return the number of comments on the provided file.
- *
- * If the file is viewed from within a collection context, this should
- * return the count of comments in that collection. Otherwise (gallery
- * view), it should return the count from the collection with most comments.
- */
getCommentCount: (annotatedFile: T) => number;
- /**
- * Return `true` if social buttons (like, comment) should be shown for the
- * given file.
- *
- * This is used for gallery view where the file might belong to a shared
- * collection even though we're not directly viewing that collection.
- */
shouldShowSocialButtons: (annotatedFile: T) => boolean;
- /**
- * Called when there is a keydown event, and our PhotoSwipe instance wants
- * to know if it should ignore it or handle it.
- *
- * The delegate should return true when it wants the keyboard event ignored,
- * e.g. for most keys while a viewer dialog is being displayed.
- */
shouldIgnoreKeyboardEvent: (event: KeyboardEvent) => boolean;
- /**
- * Called when the user triggers a potential action using a keyboard
- * shortcut.
- *
- * The caller does not check if the action is valid in the current context,
- * so the delegate must validate and only then perform the action if it is
- * appropriate.
- */
performKeyAction: (
action:
| "delete"
@@ -139,139 +72,32 @@ export interface FileViewerPhotoSwipeCoreOptions<
disableEscapeClose?: boolean;
disableGestureClose?: boolean;
dataSource: FileViewerPhotoSwipeDataSource;
- /**
- * `true` if we're running in the context of a logged in user, and so
- * various actions that modify the file should be shown.
- *
- * This is the static variant of various per file annotations that control
- * various modifications. If this is not `true`, then various actions like
- * favorite, delete etc are never shown. If this is `true`, then their
- * visibility depends on the corresponding annotation.
- *
- * For example, the favorite action is shown only if both this and the
- * {@link showFavorite} file annotation are true.
- */
haveUser: boolean;
- /**
- * `true` when viewing a public album.
- */
isPublicAlbum?: boolean;
- /**
- * Optional logo markup to place in the PhotoSwipe top bar.
- */
publicAlbumLogoHTML?: string;
- /**
- * `true` if the like and comment action buttons should be shown.
- *
- * These buttons are shown only when viewing files in a shared album
- * (incoming or outgoing).
- */
showSocialButtons: boolean;
- /**
- * `true` if the comments and reactions controls should be enabled.
- */
enableComment: boolean;
- /**
- * Dynamic callbacks.
- *
- * The extra level of indirection allows these to be updated without
- * recreating us.
- */
delegate: FileViewerPhotoSwipeDelegate<T>;
- /**
- * Called when the file viewer is closed.
- */
onClose: () => void;
- /**
- * Called whenever the slide is initially displayed or changes, to obtain
- * various derived data for the file that is about to be displayed.
- *
- * @param file The current {@link EnteFile}. This is the same value as the
- * corresponding value in the current index of {@link getFiles} returned by
- * the delegate.
- *
- * @param itemData This is the best currently available {@link ItemData}
- * corresponding to the current file.
- */
onAnnotate: (file: EnteFile, itemData: ItemData) => T;
- /**
- * Called when the user activates the info action on a file.
- */
onViewInfo: (annotatedFile: T) => void;
- /**
- * Called when the user activates the comments action on a file.
- */
onViewComments: () => void;
- /**
- * Called when the user activates the likes action on a file (right-click on heart).
- */
onViewLikes: () => void;
- /**
- * Called when the user clicks the like button (left-click on heart).
- */
onLikeClick: () => void;
- /**
- * Called when the user activates the download action on a file.
- */
onDownload: (annotatedFile: T) => void;
- /**
- * Called when the user activates the more action.
- *
- * @param buttonElement The more button DOM element.
- */
onMore: (buttonElement: HTMLElement) => void;
}
-/**
- * The ID that is used by the "more" action button (if one is being displayed).
- *
- * @see also {@link moreMenuID}.
- */
export const moreButtonID = "ente-pswp-more-button";
-/**
- * The ID this is expected to be used by the more menu that is shown in response
- * to the more action button being activated.
- *
- * @see also {@link moreButtonID}.
- */
export const moreMenuID = "ente-pswp-more-menu";
-/**
- * This is the timeout after which the controls are hidden
- * by triggering the function for the H shortcut.
- */
const fullscreenControlsAutoHideDelayMS = 3000;
-/**
- * A wrapper over {@link PhotoSwipe} to tailor its interface for use by our file
- * viewer.
- *
- * This is somewhat akin to the {@link PhotoSwipeLightbox}, except this doesn't
- * have any UI of its own, it only modifies PhotoSwipe Core's behaviour.
- *
- * [Note: PhotoSwipe]
- *
- * PhotoSwipe is a library that behaves similarly to the OG "lightbox" image
- * gallery JavaScript component from the middle ages.
- *
- * We don't need the lightbox functionality since we already have our own
- * thumbnail list (the "gallery"), so we only use the "Core" PhotoSwipe module
- * as our image viewer component.
- *
- * When the user clicks on one of the thumbnails in our gallery, we make the
- * root PhotoSwipe component visible. Within the DOM this is a dialog-like div
- * that takes up the entire viewport, shows the image, various controls etc.
- *
- * Documentation: https://photoswipe.com/.
- */
export class FileViewerPhotoSwipe<
T extends FileViewerPhotoSwipeAnnotatedFile =
FileViewerPhotoSwipeAnnotatedFile,
> {
- /**
- * The PhotoSwipe instance which we wrap.
- */
private pswp: PhotoSwipe;
constructor({
@@ -296,58 +122,19 @@ export class FileViewerPhotoSwipe<
onMore,
}: FileViewerPhotoSwipeCoreOptions<T>) {
const pswp = new PhotoSwipe({
- // Opaque background.
bgOpacity: 1,
- // The default, "zoom", cannot be used since we're not animating
- // from a thumbnail, so effectively "fade" is in effect anyway. Set
- // it still, just for and explicitness and documentation.
showHideAnimationType: "fade",
- // The default imageClickAction is "zoom-or-close". When the image
- // is small and cannot be zoomed into further (which is common when
- // just the thumbnail has been loaded), this causes PhotoSwipe to
- // close. Disable this behaviour.
+ // PhotoSwipe otherwise closes a loaded thumbnail that cannot zoom.
clickToCloseNonZoomable: false,
- // The default `bgClickAction` is "close", but it is not always
- // apparent where the background is and where the controls are,
- // since everything is black, and so accidentally closing PhotoSwipe
- // is easy.
- //
- // Disable this behaviour, instead repurposing this action to behave
- // the same as the `tapAction` ("tap on PhotoSwipe viewport
- // content") and toggle the visibility of UI controls (We also have
- // auto hide based on mouse activity, but that would not have any
- // effect on touch devices)
+ // The background boundary is ambiguous, so taps only toggle controls.
bgClickAction: "toggle-controls",
- // In single-file public viewer mode we keep Escape for nested UI
- // interactions while preventing accidental viewer closure.
escKey: !disableEscapeClose,
- // Dedicated single-file viewer mode is page-like; gesture-driven
- // dismissals should not tear down the underlying viewer.
pinchToClose: !disableGestureClose,
closeOnVerticalDrag: !disableGestureClose,
- // At least on macOS, manual zooming with the trackpad is very
- // cumbersome (possibly because of the small multiplier in the
- // PhotoSwipe source, but I'm not sure). The other option to do a
- // manual zoom is to scroll (e.g. with the trackpad) but with the
- // CTRL key pressed, however on macOS this invokes the system zoom
- // if enabled in accessibility settings.
- //
- // Taking a step back though, the PhotoSwipe viewport is fixed, so
- // we can just directly map wheel / trackpad scrolls to zooming.
wheelToZoom: true,
- // Chrome yells about incorrectly mixing focus and aria-hidden if we
- // leave this at the default (true) and then swipe between slides
- // fast, or show MUI drawers etc.
- //
- // See: [Note: Workarounds for unactionable ARIA warnings], but time
- // with a different library.
+ // PhotoSwipe's focus trap conflicts with MUI drawers and fast swipes.
trapFocus: false,
- // Set the index within files that we should open to. Subsequent
- // updates to the index will be tracked by PhotoSwipe internally.
index: initialIndex,
- // Use "pswp-ente" as the main class name. Note that this is not
- // necessary, we could've target the "pswp" class too in our CSS
- // since we only have a single PhotoSwipe instance.
mainClass: isPublicAlbum
? "pswp-ente pswp-ente-public-album"
: "pswp-ente",
@@ -360,30 +147,8 @@ export class FileViewerPhotoSwipe<
this.pswp = pswp;
- // Various helper routines to obtain the file at `currIndex`.
-
- /**
- * Derived data about the currently displayed file.
- *
- * This is recomputed on-demand (by using the {@link onAnnotate}
- * callback) each time the slide changes, and cached until the next
- * slide change.
- *
- * Instead of accessing this property directly, code should funnel
- * through the `currentAnnotatedFile` helper function.
- */
let _currentAnnotatedFile: T | undefined;
- /**
- * Non-null assert and casted the given {@link SlideData} as
- * {@link ItemData}.
- *
- * PhotoSwipe types specify currSlide.data to be of type `SlideData`,
- * but in our case these are {@link ItemData} instances which the type
- * doesn't reflect. So this is a method to consolidate the cast and
- * non-null assertion (the PhotoSwipe dialog shouldn't be visible if
- * there are no slides left).
- */
const asItemData = (slideData: SlideData | undefined) =>
slideData! as ItemData;
@@ -398,51 +163,18 @@ export class FileViewerPhotoSwipe<
annotatedFile?.file.id != file.id ||
annotatedFile.file.updationTime != file.updationTime
) {
- // Guard: slide data can be unavailable during state transitions.
- // If unavailable, we keep using the cached annotatedFile.
const slideData = pswp.currSlide?.data as ItemData | undefined;
if (slideData) {
annotatedFile = onAnnotate(file, slideData);
_currentAnnotatedFile = annotatedFile;
}
}
- // By design, this should never be undefined after the initial slide
- // is shown. Use non-null assertion to maintain API contract.
return annotatedFile!;
};
const currentFileAnnotation = () => currentAnnotatedFile().annotation;
- /**
- * [Note: Updates to the files prop for FileViewer]
- *
- * This function is called when the list of underlying files changes.
- *
- * These updates can be possibly spurious, since the list changes on
- * identity and not deep equality. Or they might be real but affect a
- * file that is not currently being shown.
- *
- * Apart from those cases, there are real updates that effect us:
- *
- * - If the file that was previously being shown is no longer being
- * shown (e.g. it was deleted, or if the marked it archived in a
- * context like "All" where archived files are not being shown), move
- * to the next slide if possible, or close the viewer otherwise (e.g.
- * user deleted the last one).
- *
- * - If the file that was previously being shown has moved to a new
- * index (e.g. user changed the date in the file info panel), go to
- * that new index.
- *
- * - If the file is still the same but the underlying file's updation
- * time has changed (e.g. the user changed the name of the file in the
- * file info panel), refresh the annotated file data cached by the
- * viewer.
- *
- * When handling these cases, the intent is to minimize the need to call
- * `refreshSlideContent` as much as possible since that would cause the
- * zoom and pan state to be reset too.
- */
+ // Refreshing slide content resets pan and zoom, so only do it when needed.
this.refreshSlideOnFilesUpdateIfNeeded = () => {
const prevFileID = _currentAnnotatedFile?.file.id;
if (!prevFileID) return;
@@ -452,39 +184,19 @@ export class FileViewerPhotoSwipe<
const newFile = files[pswp.currIndex];
if (newFile?.id != prevFileID) {
- // File is either no longer there, or has moved.
- //
- // In either case, after repositioning ourselves to the new
- // index we also need to refresh the next (or both) neighbours.
- //
- // E.g. assume item at index 3 was removed. After refreshing,
- // the contents of the item previously at index 4, and now at
- // index 3, would be displayed. But the preloaded slide next to
- // us (showing item at index 4) would already be displaying the
- // same item, so that also needs to be refreshed to displaying
- // the item previously at index 5 (now at index 4).
-
const newIndex = files.findIndex(({ id }) => id == prevFileID);
if (newIndex == -1) {
- // File is no longer present.
const i = pswp.currIndex;
if (i >= newFileCount) {
- // If the last slide was removed, take one step back
- // first (the code that calls us ensures that we don't
- // get called if there are no more slides left).
this.pswp.prev();
}
- // Refresh the slide at current index (the erstwhile
- // neighbour), and refresh its subsequent neighbour (to get
- // the new neighbour).
+ // The preloaded neighbour otherwise repeats the newly current file.
pswp.refreshSlideContent(i);
pswp.refreshSlideContent(i + 1 == newFileCount ? 0 : i + 1);
} else {
- // File has moved. Go to new index, and also refresh both
- // its neighbours.
const i = newIndex;
pswp.goTo(i);
@@ -492,25 +204,15 @@ export class FileViewerPhotoSwipe<
pswp.refreshSlideContent(i + 1 == newFileCount ? 0 : i + 1);
}
} else {
- // Calling `currentAnnotatedFile` has the side effect of
- // refreshing the cached annotated file if the `updationTime`
- // has changed.
currentAnnotatedFile();
}
};
- /**
- * File (ID)s for which we should render the original, non-streamable,
- * video even if a HLS playlist is available.
- */
const originalVideoFileIDs = new Set<number>();
const intendedVideoQualityForFileID = (fileID: number) =>
originalVideoFileIDs.has(fileID) ? "original" : "auto";
- // Provide data about slides to PhotoSwipe via callbacks
- // https://photoswipe.com/data-sources/#dynamically-generated-data
-
pswp.addFilter("numItems", () => delegate.getFiles().length);
pswp.addFilter("itemData", (_, index) => {
@@ -523,10 +225,7 @@ export class FileViewerPhotoSwipe<
file,
{ videoQuality },
() => {
- // When we get updated item data,
- // 1. Clear cached data.
_currentAnnotatedFile = undefined;
- // 2. Request a refresh.
pswp.refreshSlideContent(index);
},
);
@@ -561,89 +260,33 @@ export class FileViewerPhotoSwipe<
return asItemData(content.data).isContentZoomable ?? isZoomable;
});
- /**
- * File IDs for which we've already done initial live photo playback
- * attempts in the current session (invocation of file viewer).
- *
- * This not only allows us to skip triggering initial playback when
- * coming back to the same slide again (a behavioural choice), it also
- * allows us to skip retriggering playback when decoding of the image
- * component completes (a functional need).
- */
+ // This also prevents image decoding from replaying a live photo.
const livePhotoInitialVisitedFileIDs = new Set<number>();
- /**
- * Last state of the live photo playback on initial display.
- */
let livePhotoPlayInitial = true;
- /**
- * Set to the event listener that will be called at the end of the
- * initial playback of a live photo on the currently displayed slide.
- *
- * This will be present only during the initial playback (it will be
- * cleared when initial playback completes), and can also thus be used
- * as a pseudo `isPlayingLivePhotoInitial`.
- */
let livePhotoPlayInitialEndedEvent:
| { listener: () => void; video: HTMLVideoElement }
| undefined;
- /**
- * Last state of the live photo muted toggle.
- */
let livePhotoMute = true;
- /**
- * The live photo playback toggle DOM button element.
- */
let livePhotoPlayButtonElement: HTMLElement | undefined;
- /**
- * The live photo muted toggle DOM button element.
- */
let livePhotoMuteButtonElement: HTMLElement | undefined;
- /**
- * Update the state of the given {@link videoElement} and the
- * {@link livePhotoPlayButtonElement} to reflect
- * {@link livePhotoPlayInitial}.
- *
- * [Note: Live photo playback]
- *
- * 1. When opening a live photo, play it once unless
- * {@link livePhotoPlayInitial} is disabled. This is the behaviour
- * controlled by the {@link livePhotoUpdatePlayInitial} function.
- *
- * 2. If the user toggles playback of during the initial video playback,
- * then remember their choice for the current session (invocation of
- * file viewer) by disabling {@link livePhotoPlayInitial}.
- *
- * 3. Also keep track of which files have already been initial played in
- * the current session (using {@link livePhotoInitialVisitedFileIDs}).
- *
- * 3. Post initial playback, user can play the video again in a loop by
- * activating the {@link livePhotoPlayButtonElement}, which triggers
- * the {@link livePhotoUpdatePlayToggle} function (and also resets
- * {@link livePhotoPlayInitial}).
- */
const livePhotoUpdatePlayInitial = (video: HTMLVideoElement) => {
livePhotoUpdateUIState(video);
- // Ignore if we've already visited this file.
const currFileID = currSlideData().fileID;
if (livePhotoInitialVisitedFileIDs.has(currFileID)) {
return;
}
- // Otherwise mark it as visited.
livePhotoInitialVisitedFileIDs.add(currFileID);
- // Remove any loop attributes we might've inherited from a
- // previously displayed live photos elements on the current slide.
video.removeAttribute("loop");
- // Clear any other initial playback listeners.
if (livePhotoPlayInitialEndedEvent) {
const { video, listener } = livePhotoPlayInitialEndedEvent;
video.removeEventListener("ended", listener);
@@ -651,12 +294,6 @@ export class FileViewerPhotoSwipe<
}
if (livePhotoPlayInitial) {
- // Initial playback is enabled - Play the video once.
- //
- // There are a few playback cases (initial, resumed, adjacent
- // slide with a reused video element, new slide with a new video
- // element). Always start at the beginning in all cases for user
- // the feel the app is responding consistently.
video.currentTime = 0;
void abortablePlayVideo(video);
video.style.display = "initial";
@@ -686,38 +323,20 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * See: [Note: Live photo playback]
- *
- * This function handles the playback toggled via an explicit user
- * action (button activation or keyboard shortcut).
- */
const livePhotoUpdatePlayToggle = (video: HTMLVideoElement) => {
if (video.paused || video.ended) {
- // Add the loop attribute.
video.setAttribute("loop", "");
- // Take an explicit playback trigger as a signal to reset the
- // initial playback flag.
- //
- // This is the only way for the user to reset the initial
- // playback state (short of repopening the file viewer).
livePhotoPlayInitial = true;
video.currentTime = 0;
void abortablePlayVideo(video);
} else {
- // Remove the loop attribute (not necessarily needed because we
- // remove it on slide change too, but good to clean up after
- // ourselves).
video.removeAttribute("loop");
- // If we're in the middle of the initial playback, remember the
- // user's choice to disable autoplay.
if (livePhotoPlayInitialEndedEvent) {
livePhotoPlayInitial = false;
- // And reset the event handler.
const { video, listener } = livePhotoPlayInitialEndedEvent;
video.removeEventListener("ended", listener);
livePhotoPlayInitialEndedEvent = undefined;
@@ -729,19 +348,10 @@ export class FileViewerPhotoSwipe<
livePhotoUpdateUIState(video);
};
- /**
- * A wrapper over video.play that prevents Chrome from spamming the
- * console with errors about interrupted plays when scrolling through
- * files fast by keeping arrow keys pressed, or when the slide is reloaded.
- */
const abortablePlayVideo = async (videoElement: HTMLVideoElement) => {
try {
await videoElement.play();
} catch (e) {
- // Known message strings prefixes.
- // - "The play() request was interrupted by a call to pause()."
- // - "The play() request was interrupted because the media was removed from the document."
-
if (
e instanceof Error &&
e.name == "AbortError" &&
@@ -754,10 +364,6 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * Update the state of the given {@link videoElement} and the
- * {@link livePhotoMuteButtonElement} to reflect {@link livePhotoMute}.
- */
const livePhotoUpdateMute = (video: HTMLVideoElement) => {
const button = livePhotoMuteButtonElement;
if (button) showIf(button, true);
@@ -771,10 +377,6 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * Toggle the playback, if possible, of a live photo that's being shown
- * on the current slide.
- */
const livePhotoTogglePlayIfPossible = () => {
const buttonElement = livePhotoPlayButtonElement;
const video = livePhotoVideoOnSlide(pswp.currSlide);
@@ -783,10 +385,6 @@ export class FileViewerPhotoSwipe<
livePhotoUpdatePlayToggle(video);
};
- /**
- * Toggle the muted status, if possible, of a live photo that's being shown
- * on the current slide.
- */
const livePhotoToggleMuteIfPossible = () => {
const buttonElement = livePhotoMuteButtonElement;
const video = livePhotoVideoOnSlide(pswp.currSlide);
@@ -796,59 +394,24 @@ export class FileViewerPhotoSwipe<
livePhotoUpdateMute(video);
};
- /**
- * The DOM element housing the media-control-bar and friends.
- */
let mediaControlsContainerElement: HTMLElement | undefined;
- /**
- * True if the next change to the videoQuality is initiated by us. This
- * is used by the "change" event listener to ignore these events,
- * avoiding a cyclic update loop.
- */
let shouldIgnoreNextVideoQualityChange = false;
- /**
- * Update the media controls for the given {@link itemData}.
- *
- * - Show controls only for videos.
- * - Keep controls visible but disabled while video playback is loading.
- * - Link controls to the media controller once available.
- */
+ // Media Chrome does not reconnect its controls until the next tick on reopen.
const updateVideoControlsAndPlayback = (itemData: ItemData) => {
- // For reasons possibly related to the 1 tick wait in the hls-video
- // implementation (`await Promise.resolve()`), the association
- // between media-controller and media-control-bar doesn't get
- // established on the first slide if we reopen the file viewer.
- //
- // See also: https://github.com/muxinc/media-chrome/issues/940
- //
- // As a workaround, defer the association to the next tick.
setTimeout(() => _updateVideoControlsAndPlayback(itemData), 0);
};
- /**
- * Handle click on the media-fullscreen-button by intercepting it and
- * using document-level fullscreen instead.
- *
- * The default behavior of media-fullscreen-button puts only the
- * media-controller element into fullscreen, which hides the PhotoSwipe
- * UI controls (close, info, navigation, etc.). By using document-level
- * fullscreen on document.body, all controls remain accessible.
- *
- * In fullscreen mode, we hide the top navigation bar and only show the
- * video timeline controls at the bottom (with auto-hide behavior).
- */
const handleFullscreenButtonClick = (e: Event) => {
e.stopPropagation();
e.preventDefault();
if (document.fullscreenElement) {
void document.exitFullscreen();
} else {
+ // Fullscreen the document so PhotoSwipe controls remain accessible.
void document.body.requestFullscreen();
- // Hide top navigation bar in fullscreen, show only video controls
pswp.element?.classList.add("pswp--video-fullscreen");
- // Track mouse movement to show controls when near bottom
document.addEventListener(
"mousemove",
handleMouseMoveInFullscreen,
@@ -856,19 +419,12 @@ export class FileViewerPhotoSwipe<
}
};
- // Timer variable for hiding the controls
let fullscreenUIControlsHideTimer:
| ReturnType<typeof setTimeout>
| undefined;
- /**
- * This variable is used to check whether the controls were
- * intentionally hidden by the H keypress, if so then
- * moving the mouse no longer bring the conrol back.
- */
let areFullscreenUIControlsHiddenByShortcut = false;
- // Function to clear the timeout.
const clearFullscreenUIControlsHideTimer = () => {
if (fullscreenUIControlsHideTimer) {
clearTimeout(fullscreenUIControlsHideTimer);
@@ -876,10 +432,6 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * Function start the 3 second timer that hides the main Photoswipe UI
- * controls in the fullscreen.
- */
const scheduleFullscreenUIControlsAutoHide = () => {
clearFullscreenUIControlsHideTimer();
fullscreenUIControlsHideTimer = setTimeout(() => {
@@ -888,11 +440,6 @@ export class FileViewerPhotoSwipe<
}, fullscreenControlsAutoHideDelayMS);
};
- /**
- * If the photoswipe controls were actually auto hidden
- * and not by the H shortcut then, this function brings
- * them back on mouse movement.
- */
const handleFullscreenMouseMove = () => {
if (!document.fullscreenElement) return;
if (areFullscreenUIControlsHiddenByShortcut) return;
@@ -901,9 +448,6 @@ export class FileViewerPhotoSwipe<
scheduleFullscreenUIControlsAutoHide();
};
- /**
- * Update UI state when fullscreen mode changes (e.g., user presses Esc).
- */
const handleFullscreenChange = () => {
if (document.fullscreenElement) {
document.addEventListener(
@@ -922,7 +466,6 @@ export class FileViewerPhotoSwipe<
areFullscreenUIControlsHiddenByShortcut = false;
pswp.element?.classList.add("pswp--ui-visible");
- // Exiting fullscreen - restore the top navigation bar
pswp.element?.classList.remove("pswp--video-fullscreen");
pswp.element?.classList.remove("pswp--controls-visible");
document.removeEventListener(
@@ -935,24 +478,15 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * Timer ID for hiding video controls after mouse inactivity in
- * fullscreen.
- */
let hideVideoControlsTimer: ReturnType<typeof setTimeout> | undefined;
- /**
- * Show video controls on mouse movement, hide after inactivity.
- */
const handleMouseMoveInFullscreen = () => {
pswp.element?.classList.add("pswp--controls-visible");
- // Clear any pending hide timer
if (hideVideoControlsTimer) {
clearTimeout(hideVideoControlsTimer);
}
- // Hide controls after inactivity
hideVideoControlsTimer = setTimeout(() => {
pswp.element?.classList.remove("pswp--controls-visible");
hideVideoControlsTimer = undefined;
@@ -992,8 +526,6 @@ export class FileViewerPhotoSwipe<
if (qualityMenu instanceof MediaChromeMenu) {
const { videoPlaylistURL, fileID } = itemData;
- // Hide the auto option, keeping track of if we did indeed
- // change something.
const item = qualityMenu.radioGroupItems[0]!;
let didChangeHide = false;
if (item.hidden && videoPlaylistURL) {
@@ -1009,33 +541,20 @@ export class FileViewerPhotoSwipe<
videoPlaylistURL
? t("auto")
: t("original");
- // Check first to avoid spurious updates.
if (qualityMenu.value != value) {
- // Set a flag to avoid infinite update loop.
shouldIgnoreNextVideoQualityChange = true;
- // Setting the value will close it.
qualityMenu.value = value;
} else {
- // Close it ourselves otherwise if we changed the menu.
if (didChangeHide) {
closeMediaChromeSettingsMenuIfOpen();
}
}
}
- // Autoplay (unless the video has ended).
const video = videoVideoEl;
if (video?.paused && !video.ended) void video.play();
};
- /**
- * Toggle the settings menu by activating the menu button.
- *
- * This should be more robust than us trying to reverse engineer the
- * internal media chrome logic to open and close the menu. However, the
- * caveat is that this will only work for closing the menu (our goal)
- * if the menu is already open.
- */
const toggleMediaChromeSettingsMenu = () => {
const menuButton = document.querySelector(
"media-settings-menu-button",
@@ -1043,11 +562,7 @@ export class FileViewerPhotoSwipe<
if (menuButton instanceof MediaChromeMenuButton) {
menuButton.handleClick();
- // See: [Note: Media chrome focus workaround]
- //
- // Whatever media chrome is doing internally, it requires us to
- // drop the focus multiple times (Removing either of these calls
- // is not enough).
+ // Media Chrome retains invisible focus; both blur passes are required.
const blurAllFocused = () =>
document
.querySelectorAll(":focus")
@@ -1064,15 +579,7 @@ export class FileViewerPhotoSwipe<
};
pswp.on("contentAppend", (e) => {
- // PhotoSwipe emits stale contentAppend events. e.g. when changing
- // the video quality, we'll first get "contentAppend" (and "change")
- // with the latest item data, but then later PhotoSwipe will call
- // "contentAppend" again with stale data.
- //
- // To ignore these, we check the `hasSlide` attribute. I'm not sure
- // if this is a foolproof workaround.
- //
- // See also https://github.com/dimsemenov/PhotoSwipe/issues/2045.
+ // PhotoSwipe can emit this later for content it already detached.
if (!e.content.hasSlide) {
log.debug(() => ["Ignoring stale contentAppend", e]);
return;
@@ -1080,23 +587,15 @@ export class FileViewerPhotoSwipe<
const { fileID, fileType, videoURL } = asItemData(e.content.data);
- // For the initial slide, "contentAppend" will get called after the
- // "change" event, so we need to wire up the controls, or hide them,
- // for the initial slide here also (in addition to in "change").
+ // Initial contentAppend can follow change, so wire controls here too.
if (currSlideData().fileID == fileID) {
updateVideoControlsAndPlayback(currSlideData());
}
if (fileType != FileType.livePhoto || !videoURL) {
- // Not a live photo, or its video hasn't loaded yet.
return;
}
- // Rest of this function deals with live photos.
-
- // This slide is displaying a live photo. Append a video element to
- // show its video part.
-
const img = e.content.element!;
const video = createElementFromHTMLString(
livePhotoVideoHTML(videoURL),
@@ -1104,30 +603,18 @@ export class FileViewerPhotoSwipe<
const container = e.content.slide!.container;
container.style = "position: relative";
container.appendChild(video);
- // Set z-index to 1 to keep it on top, and set pointer-events to
- // none to pass the clicks through.
video.style =
"position: absolute; top: 0; left: 0; z-index: 1; pointer-events: none;";
- // Size it to the underlying image.
video.style.width = img.style.width;
video.style.height = img.style.height;
- // "contentAppend" can get called both before, or after, "change",
- // and we need to handle both potential sequences for the initial
- // display of the video. Here we handle the case where "change" has
- // already been called, but now "contentAppend" is happening.
-
if (currSlideData().fileID == fileID) {
livePhotoUpdatePlayInitial(video);
livePhotoUpdateMute(video);
}
});
- /**
- * Helper function to extract the video element from a slide that is
- * showing a live photo.
- */
const livePhotoVideoOnSlide = (slide: typeof pswp.currSlide) =>
asItemData(slide?.data).fileType == FileType.livePhoto
? slide?.container.getElementsByTagName("video")[0]
@@ -1136,46 +623,20 @@ export class FileViewerPhotoSwipe<
pswp.on("imageSizeChange", ({ content, width, height }) => {
const video = livePhotoVideoOnSlide(content.slide);
if (!video) {
- // We might have been called before "contentAppend".
return;
}
- // This slide is displaying a live photo. Resize the size of the
- // video element to match that of the image.
-
video.style.width = `${width}px`;
video.style.height = `${height}px`;
});
- /**
- * Get the video element, if any, that is a descendant of the given HTML
- * element.
- *
- * While the return type is an {@link HTMLVideoElement}, the result can
- * also be an instance of a media-chrome `CustomVideoElement`,
- * specifically a {@link HlsVideoElement}.
- * https://github.com/muxinc/media-elements/blob/main/packages/hls-video-element/hls-video-element.js
- *
- * The media-chrome `CustomVideoElement`s provide the same API as the
- * browser's built-in {@link HTMLVideoElement}s, so we can use the same
- * methods on them.
- *
- * For ergonomic use at call sites, it accepts an optional.
- */
const queryVideoElement = (element: HTMLElement | undefined) =>
element?.querySelector<HTMLVideoElement>("video, hls-video");
pswp.on("contentDeactivate", (e) => {
- // PhotoSwipe invokes this event when moving away from a slide.
- //
- // However it might not have an effect until we move out of preload
- // range. See: [Note: File viewer preloading and contentDeactivate].
-
const fileID = asItemData(e.content.data).fileID;
if (fileID) dataSource.forgetItemDataForFileIDIfNeeded(fileID);
- // Pause the video element, if any, when we move away from the
- // slide.
const video = queryVideoElement(e.content.slide?.container);
video?.pause();
});
@@ -1197,28 +658,15 @@ export class FileViewerPhotoSwipe<
dataSource.forgetExifForItemData(asItemData(e.content.data)),
);
- /**
- * If the current slide is showing a video, then the DOM video element
- * showing that video.
- *
- * See also {@link queryVideoElement}.
- */
let videoVideoEl: HTMLVideoElement | undefined;
- /**
- * The epoch time (milliseconds) when the latest slide change happened.
- */
let lastSlideChangeEpochMilli = Date.now();
pswp.on("change", () => {
const itemData = currSlideData();
- // For each slide ("item holder"), mirror the "aria-hidden" state
- // into the "inert" property so that keyboard navigation via tabs
- // does not cycle through to the hidden slides (e.g. if the hidden
- // slide is a video element with browser provided controls).
-
pswp.mainScroll.itemHolders.forEach(({ el }) => {
+ // aria-hidden alone does not remove hidden slides from tab order.
if (el.getAttribute("aria-hidden") == "true") {
el.setAttribute("inert", "");
} else {
@@ -1227,13 +675,6 @@ export class FileViewerPhotoSwipe<
});
if (itemData.fileType == FileType.video) {
- // We use content.element instead of container here because
- // pswp.currSlide.container.getElementsByTagName("video") does
- // not work for the first slide when we reach here during the
- // initial "change".
- //
- // It works subsequently, which is why, e.g., we can use it to
- // pause the video in "contentDeactivate".
const contentElement = pswp.currSlide?.content.element;
videoVideoEl = queryVideoElement(contentElement) ?? undefined;
} else {
@@ -1243,10 +684,6 @@ export class FileViewerPhotoSwipe<
lastSlideChangeEpochMilli = Date.now();
});
- /**
- * Toggle the playback, if possible, of the video that's being shown on
- * the current slide.
- */
const videoTogglePlayIfPossible = () => {
const video = videoVideoEl;
if (!video) return;
@@ -1258,15 +695,8 @@ export class FileViewerPhotoSwipe<
}
};
- /**
- * Toggle the muted status, if possible, of the video that's being shown on
- * the current slide.
- */
+ // Go through Media Chrome so its persisted mute preference stays in sync.
const videoToggleMuteIfPossible = () => {
- // Go via the media chrome mute button when muting, because
- // otherwise the local storage that the media chrome internally
- // manages ('media-chrome-pref-muted' which can be 'true' or
- // 'false') gets out of sync with the playback state.
const muteButton = document.querySelector("media-mute-button");
if (muteButton instanceof MediaMuteButton) muteButton.handleClick();
};
@@ -1283,8 +713,6 @@ export class FileViewerPhotoSwipe<
"pswp__icn-favorite-fill",
);
if (!favoriteIconFill) {
- // Early return if we're not currently being shown, to implement
- // the "IfNeeded" semantics.
return;
}
@@ -1295,14 +723,11 @@ export class FileViewerPhotoSwipe<
showIf(button, showFavorite);
if (!showFavorite) {
- // Nothing more to do.
return;
}
- // Update the button interactivity based on pending requests.
button.disabled = delegate.isFavoritePending(af);
- // Update the fill visibility based on the favorite status.
showIf(favoriteIconFill, !!delegate.isFavorite(af));
};
@@ -1315,16 +740,14 @@ export class FileViewerPhotoSwipe<
);
const heartIconOutline = document.getElementById("pswp__icn-heart");
if (!heartIconFill || !heartIconOutline) {
- // Early return if we're not currently being shown.
return;
}
const af = currentAnnotatedFile();
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
- if (!af) return; // Guard against undefined during initialization
+ if (!af) return;
const isLiked = delegate.isLiked(af);
- // Show fill (green) if liked, show outline (white) if not liked
showIf(heartIconFill, isLiked);
showIf(heartIconOutline, !isLiked);
};
@@ -1336,13 +759,12 @@ export class FileViewerPhotoSwipe<
".pswp__comment-count",
);
if (!commentCountElement) {
- // Early return if we're not currently being shown.
return;
}
const af = currentAnnotatedFile();
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
- if (!af) return; // Guard against undefined during initialization
+ if (!af) return;
const count = delegate.getCommentCount(af);
commentCountElement.textContent = String(count);
};
@@ -1370,20 +792,12 @@ export class FileViewerPhotoSwipe<
const onVideoQualityChange = () => {
if (shouldIgnoreNextVideoQualityChange) {
- // Ignore changes that we ourselves initiated on slide change.
shouldIgnoreNextVideoQualityChange = false;
return;
}
- // The menu is open at this point, so toggling it is equivalent to
- // closing it.
toggleMediaChromeSettingsMenu();
- // Currently there are only two entries in the video quality menu,
- // and the callback only gets invoked if the value gets changed from
- // the current value. So we can assume toggle semantics when
- // implementing the logic below.
-
const fileID = currentAnnotatedFile().file.id;
dataSource.forgetItemDataForFileID(fileID);
if (originalVideoFileIDs.has(fileID)) {
@@ -1392,8 +806,6 @@ export class FileViewerPhotoSwipe<
originalVideoFileIDs.add(fileID);
}
- // Refresh the slide so that the video is fetched afresh, but using
- // the updated `originalVideoFileIDs` value for it.
pswp.refreshSlideContent(pswp.currIndex);
};
@@ -1402,32 +814,12 @@ export class FileViewerPhotoSwipe<
? element.classList.remove("pswp__hidden")
: element.classList.add("pswp__hidden");
- // Add our custom UI elements to inside the PhotoSwipe dialog.
- //
- // API docs for registerElement:
- // https://photoswipe.com/adding-ui-elements/#uiregisterelement-api
- //
- // The "order" prop is used to position items. Some landmarks:
- // - counter: 5
- // - zoom: 6 (default is 10)
- // - preloader: 10 (default is 7)
- // - close: 20
pswp.on("uiRegister", () => {
const ui = pswp.ui!;
- // Move the zoom button to the left so that it is in the same place
- // as the other items like preloader or the error indicator that
- // come and go as files get loaded. Also modify the default orders
- // so that there is more space for the error / live indicators.
- //
- // We cannot use the PhotoSwipe "uiElement" filter to modify the
- // order since that only allows us to edit the DOM element, not the
- // underlying UI element data.
ui.uiElementsData.find((e) => e.name == "zoom")!.order = 6;
ui.uiElementsData.find((e) => e.name == "preloader")!.order = 10;
- // Register our custom elements...
-
if (isPublicAlbum && publicAlbumLogoHTML) {
ui.registerElement({
name: "ente-logo",
@@ -1454,7 +846,6 @@ export class FileViewerPhotoSwipe<
if (video) {
livePhotoUpdatePlayInitial(video);
} else {
- // Not a live photo, or its video hasn't loaded yet.
showIf(buttonElement, false);
}
});
@@ -1475,7 +866,6 @@ export class FileViewerPhotoSwipe<
if (video) {
livePhotoUpdateMute(video);
} else {
- // Not a live photo, or its video hasn't loaded yet.
showIf(buttonElement, false);
}
});
@@ -1499,8 +889,6 @@ export class FileViewerPhotoSwipe<
},
});
- // Only one of these two ("favorite" and "download") will end
- // up being shown, so they can safely share the same order.
if (haveUser) {
ui.registerElement({
name: "favorite",
@@ -1510,17 +898,12 @@ export class FileViewerPhotoSwipe<
html: createPSRegisterElementIconHTML("favorite"),
onInit: (buttonElement) => {
favoriteButtonElement =
- // The cast should be safe (unless there is a
- // PhotoSwipe bug) since we set isButton to true.
buttonElement as HTMLButtonElement;
pswp.on("change", updateFavoriteButtonIfNeeded);
},
onClick: handleToggleFavorite,
});
} else {
- // When we don't have a user (i.e. in the context of public
- // albums), the download button is shown (if enabled for that
- // album) instead of the favorite button as the first action.
ui.registerElement({
name: "download",
title: t("download"),
@@ -1547,10 +930,6 @@ export class FileViewerPhotoSwipe<
onClick: handleViewInfo,
});
- // Only show the more button if there are meaningful items to display.
- // When fullscreen is shown in the toolbar (showFullscreenButton=true)
- // and we're in a context without user actions (no delete, archive, etc),
- // hide the more menu since it would only contain fullscreen and shortcuts.
const shouldShowMoreButton = !showFullscreenButton || haveUser;
if (shouldShowMoreButton) {
@@ -1565,7 +944,6 @@ export class FileViewerPhotoSwipe<
buttonElement.setAttribute("aria-haspopup", "true");
},
onClick: (_, buttonElement) => {
- // See also: `resetMoreMenuButtonOnMenuClose`.
buttonElement.setAttribute("aria-controls", moreMenuID);
buttonElement.setAttribute("aria-expanded", "true");
onMore(buttonElement);
@@ -1573,7 +951,6 @@ export class FileViewerPhotoSwipe<
});
}
- // Add fullscreen button as a primary action for embed app
if (showFullscreenButton) {
ui.registerElement({
name: "fullscreen",
@@ -1599,7 +976,6 @@ export class FileViewerPhotoSwipe<
}
};
- // Update icon on fullscreen changes
document.addEventListener(
"fullscreenchange",
updateIcon,
@@ -1611,7 +987,6 @@ export class FileViewerPhotoSwipe<
);
});
- // Initialize icon state
updateIcon();
},
onClick: handleToggleFullscreen,
@@ -1620,7 +995,6 @@ export class FileViewerPhotoSwipe<
ui.registerElement({
name: "media-controls",
- // Arbitrary order towards the end.
order: 30,
appendTo: "root",
html: hlsVideoControlsHTML(),
@@ -1630,9 +1004,6 @@ export class FileViewerPhotoSwipe<
if (menu instanceof MediaChromeMenu) {
menu.addEventListener("change", onVideoQualityChange);
}
- // Override the media-fullscreen-button to use document-level
- // fullscreen instead of element-level fullscreen. This
- // ensures the PhotoSwipe UI controls remain accessible.
const fullscreenButton = element.querySelector(
"media-fullscreen-button",
);
@@ -1649,27 +1020,19 @@ export class FileViewerPhotoSwipe<
ui.registerElement({
name: "bottom-right-controls",
- // After the video controls so that we don't get occluded by
- // them (nb: the caption will hide when the video is playing).
order: 31,
appendTo: "root",
html: bottomRightControlsHTML(),
onInit: (element, pswp) => {
const captionEl =
element.querySelector<HTMLElement>(".pswp__caption")!;
- // Get the action buttons container.
const actionButtonsEl = element.querySelector<HTMLElement>(
".pswp__action-buttons",
);
const updateSocialButtonsVisibility = () => {
if (!actionButtonsEl) return;
- // Guard: _currentAnnotatedFile can be undefined during
- // initialization before the first slide is shown.
if (!_currentAnnotatedFile) return;
- // Show buttons if: static showSocialButtons is true
- // OR delegate says this file should show buttons
- // (file in shared collection).
const af = currentAnnotatedFile();
const baseShow =
showSocialButtons ||
@@ -1700,39 +1063,29 @@ export class FileViewerPhotoSwipe<
"ente-video",
fileType == FileType.video,
);
- // Update social buttons visibility on each slide change.
updateSocialButtonsVisibility();
});
- // Wire up click handler for the comment button.
const commentButton = element.querySelector<HTMLElement>(
'.pswp__action-button[aria-label="Comment"]',
);
commentButton?.addEventListener("click", onViewComments);
- // Wire up click handlers for the like button.
const likeButton = element.querySelector<HTMLElement>(
'.pswp__action-button[aria-label="Like"]',
);
- // Left-click: trigger like action (may open album selector)
likeButton?.addEventListener("click", onLikeClick);
- // Right-click: open likes sidebar
likeButton?.addEventListener("contextmenu", (e) => {
e.preventDefault();
onViewLikes();
});
- // Update like button state on slide change and initially.
pswp.on("change", updateLikeButtonIfNeeded);
updateLikeButtonIfNeeded();
- // Update comment count on slide change and initially.
pswp.on("change", updateCommentCountIfNeeded);
updateCommentCountIfNeeded();
- // Initial visibility check.
updateSocialButtonsVisibility();
},
});
});
- // Pan action handlers
-
const panner = (key: "w" | "a" | "s" | "d") => () => {
const slide = pswp.currSlide!;
const d = 80;
@@ -1753,35 +1106,19 @@ export class FileViewerPhotoSwipe<
slide.panTo(slide.pan.x, slide.pan.y);
};
- // Actions we handle ourselves.
-
const handlePreviousSlide = () => pswp.prev();
const handleNextSlide = () => pswp.next();
- /**
- * The arrow keys are used both for navigating through slides, and for
- * scrubbing through the video.
- *
- * When on a video, the navigation requires the option prefix (since
- * scrubbing through the video is a more common requirement). However
- * this breaks the user's flow when they are navigating between slides
- * fast by using the arrow keys - they land on a video and the
- * navigation stops.
- *
- * So as a special case, we keep using arrow keys for navigation for the
- * first 700 milliseconds when the user lands on a slide.
- */
+ // Arrow keys keep navigating briefly after landing on a video.
const isUserLikelyNavigatingBetweenSlides = () =>
- Date.now() - lastSlideChangeEpochMilli < 700; /* ms */
+ Date.now() - lastSlideChangeEpochMilli < 700;
const handleSeekBackOrPreviousSlide = () => {
const video = videoVideoEl;
if (
video &&
!isUserLikelyNavigatingBetweenSlides() &&
- // If the video is at the beginning, then use the left arrow to
- // move to the preview slide.
video.currentTime > 0
) {
video.currentTime = Math.max(video.currentTime - 5, 0);
@@ -1795,8 +1132,6 @@ export class FileViewerPhotoSwipe<
if (
video &&
!isUserLikelyNavigatingBetweenSlides() &&
- // If the video has ended, then use right arrow to move to the
- // next slide.
!video.ended
) {
video.currentTime = video.currentTime + 5;
@@ -1827,8 +1162,6 @@ export class FileViewerPhotoSwipe<
}
};
- // Toggle controls infrastructure
-
const handleToggleUIControls = () => {
const areUIControlsVisible =
pswp.element!.classList.toggle("pswp--ui-visible");
@@ -1842,17 +1175,12 @@ export class FileViewerPhotoSwipe<
}
};
- // Return true if the current keyboard focus is on any of the UI
- // controls (e.g. as a result of user tabbing through them).
const isFocusVisibledOnUIControl = () => {
const fv = document.querySelector(":focus-visible");
if (fv && !fv.classList.contains("pswp")) {
return true;
}
- // Media Chrome does its own thing and doesn't seem to gain the
- // :focus-visible pseudo class even though it visually looks that
- // way. We need to add a special case for it.
const f = document.querySelector(":focus");
if (f?.tagName.startsWith("MEDIA-")) {
return true;
@@ -1861,8 +1189,6 @@ export class FileViewerPhotoSwipe<
return false;
};
- // Some actions routed via the delegate
-
const handleDelete = () => delegate.performKeyAction("delete");
const handleToggleArchive = () =>
@@ -1878,19 +1204,14 @@ export class FileViewerPhotoSwipe<
pswp.on("keydown", (pswpEvent) => {
const e: KeyboardEvent = pswpEvent.originalEvent;
- // Ignore keyboard events when one of our sub-dialogs are open.
if (delegate.shouldIgnoreKeyboardEvent(e)) {
pswpEvent.preventDefault();
return;
}
const key = e.key;
- // Even though we ignore shift, Caps lock might still be on.
const lkey = e.key.toLowerCase();
- // When one of the controls on the screen has a visible focus
- // indicator, we want the Escape key to blur its focus instead of
- // closing the PhotoSwipe dialog.
if (isFocusVisibledOnUIControl() && key == "Escape") {
const activeElement = document.activeElement;
if (activeElement instanceof HTMLElement) activeElement.blur();
@@ -1898,23 +1219,10 @@ export class FileViewerPhotoSwipe<
return;
}
- // Keep the keybindings such that they don't use modifiers, because
- // these are more likely to interfere with browser shortcuts.
- //
- // For example, Cmd-D adds a bookmark, which is why we don't use it
- // for download.
- //
- // There are some exception, e.g. Ctrl/Cmd-C, which we intercept to
- // copy the image since that should match the user's expectation.
-
let cb: (() => void) | undefined;
if (e.shiftKey) {
- // Ignore except "?" for help.
if (key == "?") cb = handleHelp;
} else if (e.altKey) {
- // Ignore except if for arrow keys since when showing a video,
- // the arrow keys are used for seeking, and the normal arrow key
- // function (slide movement) needs the Alt/Opt modifier.
switch (key) {
case "ArrowLeft":
cb = handlePreviousSlide;
@@ -1924,19 +1232,13 @@ export class FileViewerPhotoSwipe<
break;
}
} else if (e.metaKey || e.ctrlKey) {
- // Ignore except Ctrl/Cmd-C for copy
if (lkey == "c") cb = handleCopy;
} else {
switch (key) {
case " ":
- // Space activates controls when they're focused, so
- // only act on it if no specific control is focused.
if (!isFocusVisibledOnUIControl()) {
cb = handleTogglePlayIfPossible;
}
- // Prevent the browser's default space behaviour of
- // scrolling the file list in the background (which is
- // not appropriate when the file viewer is visible).
if (e.target == document.body) e.preventDefault();
break;
case "Backspace":
@@ -1945,16 +1247,12 @@ export class FileViewerPhotoSwipe<
break;
case "ArrowLeft":
cb = handleSeekBackOrPreviousSlide;
- // Prevent PhotoSwipe's default handling of this key.
pswpEvent.preventDefault();
break;
case "ArrowRight":
cb = handleSeekForwardOrNextSlide;
- // Prevent PhotoSwipe's default handling of this key.
pswpEvent.preventDefault();
break;
- // We check for "?"" both with an without shift, since some
- // keyboards might have it emittable without shift.
case "?":
cb = handleHelp;
break;
@@ -1993,29 +1291,6 @@ export class FileViewerPhotoSwipe<
cb?.();
});
- /**
- * [Note: Media chrome focus workaround]
- *
- * The media-chrome-button elements (e.g, the play button, but also
- * others, including the menu) retain focus after clicking on them.
- * e.g., if I click the "media-mute-button" to activate it, then the
- * mute button grabs focus (but not :focus-visible). So it doesn't
- * appear focused visually, but then later if I press Space or Enter,
- * then the mute button activates again instead of toggling video
- * playback (as our keyboard shortcut is meant to do).
- *
- * I'm not sure who is at fault here, but this behaviour ends up being
- * irritating. e.g. say I change the quality in the menu, and press
- * space to play - well, the space no longer works because the media
- * chrome has grabbed focus and instead activates itself, reopening the
- * settings menu.
- *
- * As a workaround, we ask media chrome to drop focus on mouse clicks.
- * This should not impact keyboard activations.
- *
- * This workaround is likely to cause problems in the future, but I
- * can't find a better way short of upstream media chrome changes.
- */
const blurMediaChromeFocus = (e: MouseEvent) => {
const target = e.target;
if (target instanceof HTMLElement) {
@@ -2039,8 +1314,6 @@ export class FileViewerPhotoSwipe<
);
});
- // The PhotoSwipe dialog has being closed and the animations have
- // completed.
pswp.on("destroy", () => {
pswp.element?.removeEventListener(
"mousedown",
@@ -2064,77 +1337,29 @@ export class FileViewerPhotoSwipe<
hideVideoControlsTimer = undefined;
}
dataSource.fileViewerDidClose();
- // Let our parent know that we have been closed.
onClose();
});
- // Let our data source know that we're about to open.
dataSource.fileViewerWillOpen();
- // Initializing PhotoSwipe adds it to the DOM as a dialog-like div with
- // the class "pswp".
pswp.init();
}
- /**
- * Close this instance of {@link FileViewerPhotoSwipe} if it hasn't itself
- * initiated the close.
- *
- * This instance **cannot** be used after this function has been called.
- */
closeIfNeeded() {
- // Closing PhotoSwipe removes it from the DOM.
- //
- // This will only have an effect if we're being closed externally (e.g.
- // if the user selects an album in the file info).
- //
- // If this cleanup function is running in the sequence where we were
- // closed internally (e.g. the user activated the close button within
- // the file viewer), then PhotoSwipe will ignore this extra close.
+ // PhotoSwipe instances cannot be reused after destroy.
this.pswp.close();
}
- /**
- * Reload the current slide, asking the data source for its data afresh.
- */
refreshCurrentSlideContent() {
this.pswp.refreshSlideContent(this.pswp.currIndex);
}
- /**
- * Ask the delegate for the files information afresh, and perform the
- * sequence described in [Note: Updates to the files prop for FileViewer].
- */
refreshSlideOnFilesUpdateIfNeeded: () => void;
-
- /**
- * Refresh the favorite button (if indeed it is visible at all) on the
- * current slide, asking the delegate for the latest state.
- *
- * We do this piecemeal update instead of a full refresh because a full
- * refresh would cause, e.g., the pan and zoom to be reset.
- */
refreshCurrentSlideFavoriteButtonIfNeeded: () => void;
-
- /**
- * Refresh the like button (heart) on the current slide, asking the
- * delegate for the latest like state.
- */
refreshCurrentSlideLikeButtonIfNeeded: () => void;
-
- /**
- * Refresh the comment count on the current slide, asking the delegate
- * for the latest comment count.
- */
refreshCurrentSlideCommentCountIfNeeded: () => void;
}
-// Requires the following imports to register the Web components we use:
-//
-// import "hls-video-element";
-// import "media-chrome";
-// import "media-chrome/menu";
-//
const hlsVideoHTML = (url: string, mediaControllerID: string) => `
<media-controller id="${mediaControllerID}" nohotkeys>
<hls-video playsinline slot="media" src="${url}"></hls-video>
@@ -2147,37 +1372,6 @@ const videoHTML = (url: string, mediaControllerID: string) => `
</media-controller>
`;
-/**
- * HTML for controls associated with {@link hlsVideoHTML} or {@link videoHTML}.
- *
- * To make these functional, the `media-control-bar` requires the
- * `mediacontroller="${mediaControllerID}"` attribute.
- *
- * Notes:
- *
- * - Examples: https://media-chrome.mux.dev/examples/vanilla/
- *
- * - When PiP is active and the video moves out, the browser displays some
- * indicator (browser specific) in the in-page video element. This element and
- * text is not under our control.
- *
- * - The media-cast-button currently doesn't work with the `hls-video` player.
- *
- * - We don't use media chrome tooltips: Media chrome has mechanism for
- * statically providing translations but it wasn't working when I tried with
- * 4.9.0. The media chrome tooltips also get clipped for the cornermost
- * buttons. Finally, the rest of the buttons on this screen don't have a
- * tooltip either.
- *
- * Revisit this when we have a custom tooltip element we can then also use on
- * this screen, which can also be used enhancement for the other buttons on
- * this screen which use "title" (which get clipped when they are multi-word).
- *
- * - See: [Note: Spurious media chrome resize observer errors]
- *
- * - If something is not working as expected, a possible reason might be the
- * focus workaround. See: [Note: Media chrome focus workaround].
- */
const hlsVideoControlsHTML = () => `
<div>
<media-settings-menu id="ente-settings-menu" hidden anchor="ente-settings-menu-btn">
@@ -2216,24 +1410,12 @@ const hlsVideoControlsHTML = () => `
</div>
`;
-// playsinline will play the video inline on mobile browsers (where the default
-// is to open a full screen player).
const livePhotoVideoHTML = (videoURL: string) => `
<video muted playsinline oncontextmenu="return false;">
<source src="${videoURL}" />
</video>
`;
-/**
- * HTML for the bottom controls (caption on left, action buttons on right).
- *
- * The caption uses the line-clamp CSS property, which behaves unexpectedly
- * when we also assign padding to the "p" element on which we're setting the
- * line clamp: the "clipped" lines show through in the padding area.
- *
- * As a workaround, wrap the p in a div. Set the line-clamp on the p, and the
- * padding on the div.
- */
const bottomRightControlsHTML = () => `
<div class="pswp__caption"><p></p></div>
<div class="pswp__action-buttons">
@@ -2247,12 +1429,6 @@ const bottomRightControlsHTML = () => `
</div>
`;
-/**
- * Truncate caption text to 154 characters.
- *
- * @returns An object with the (possibly truncated) text and a flag indicating
- * whether or not the text was truncated.
- */
const truncateCaptionIfNeeded = (
text: string | undefined,
): { text: string | undefined; wasTruncated: boolean } => {
@@ -2264,16 +1440,11 @@ const truncateCaptionIfNeeded = (
const createElementFromHTMLString = (htmlString: string) => {
const template = document.createElement("template");
- // Excess whitespace causes excess DOM nodes, causing our firstChild to not
- // be what we wanted them to be.
+ // Whitespace would become firstChild instead of the requested element.
template.innerHTML = htmlString.trim();
return template.content.firstChild!;
};
-/**
- * Update the ARIA attributes for the button that controls the more menu when
- * the menu is closed.
- */
export const resetMoreMenuButtonOnMenuClose = (buttonElement: HTMLElement) => {
buttonElement.removeAttribute("aria-controls");
buttonElement.removeAttribute("aria-expanded");
diff --git a/web/packages/gallery/services/download-core.ts b/web/packages/gallery/services/download-core.ts
index 92a36ce389..e10ffab533 100644
--- a/web/packages/gallery/services/download-core.ts
+++ b/web/packages/gallery/services/download-core.ts
@@ -12,89 +12,22 @@ import { FileType } from "ente-media/file-type";
import { decodeLivePhoto } from "ente-media/live-photo";
import { detectFileTypeInfoFromChunk } from "../utils/detect-type";
-/**
- * URL(s) for the original image or video, alongwith with potential conversions
- * applied to make it more likely that the browser will be able to render (or
- * play) it.
- *
- * The word "renderable" or "playable" is not a guarantee, but rather a best
- * effort indicator as we might not always be able to convert all formats to
- * something that the browser can show.
- */
export type RenderableSourceURLs =
| {
type: "image";
- /**
- * An object URL that can be directly provided to the browser to get
- * it to render the image.
- *
- * This is a best effort basis. Not all images will be renderable in
- * all browsers, so the file might still not be previewable.
- *
- * In cases where we detect that the browser can natively render this
- * image, this can be just the an object URL created from
- * {@link originalImageBlob}. In other cases, this will point to a
- * separate, converted blob.
- */
imageURL: string;
- /**
- * A {@link Blob} from the original image.
- *
- * This is useful for extracting the Exif.
- */
originalImageBlob: Blob;
- /**
- * Best effort attempt at obtaining the MIME type.
- *
- * It should usually be present, but it is not guaranteed that we'll
- * be able to detect the MIME type for all images. However, the only
- * scenario where it is needed currently is by the image editor, where
- * if we can't detect the MIME type, then the image can't be shown (or
- * edited) in the current browser anyway.
- */
mimeType?: string;
}
- | {
- type: "video";
- /**
- * An object URL that can be directly provided to the browser to get
- * it to render the image.
- *
- * This is a best effort basis. Not all videos will be playable in all
- * browsers, so the file might still not be previewable.
- */
- videoURL: string;
- }
+ | { type: "video"; videoURL: string }
| {
type: "livePhoto";
- /**
- * Similar to the {@link imageURL} for type "image", except
- * as a promise since we might want to operate on the different
- * components of a live image in a staggered order.
- */
imageURL: () => Promise<string>;
- /**
- * Similar to the {@link originalImageBlob} for type "image".
- */
originalImageBlob: Blob;
- /**
- * Similar to the {@link videoURL} for type "video", except as
- * a promise since we might want to operate on the different
- * components of a live image in a staggered order.
- */
videoURL: () => Promise<string>;
};
-/**
- * Options for file downloads.
- */
export interface FileDownloadOpts {
- /**
- * `true` if the request is for a background task. These are considered less
- * latency sensitive than user initiated interactive requests.
- *
- * See: [Note: User initiated vs background downloads of files].
- */
background?: boolean;
}
@@ -112,67 +45,18 @@ export interface DownloadManagerTransport {
) => Promise<string>;
}
-/**
- * A class that tracks the state of in-progress downloads and conversions,
- * including caching them for subsequent retrieval if appropriate.
- */
export class DownloadManagerCore {
- /**
- * Local cache for thumbnail blobs.
- *
- * `undefined` indicates that the cache has not yet been initialized. It is
- * also possible that the cache might not be available, in which case it'd
- * be set to `null`.
- */
private thumbnailCache: BlobCache | null | undefined;
- /**
- * An in-memory cache for an object URL to a file's thumbnail.
- *
- * This object URL can be directly used to render the thumbnail (e.g. in an
- * img tag). The entries are keyed by the file ID.
- */
private thumbnailURLPromises = new Map<
number,
Promise<string | undefined>
>();
- /**
- * An in-memory cache for an object URL to a file's original data.
- *
- * Unlike {@link thumbnailURLPromises}, there is no guarantee that the
- * browser will be able to render the original file (e.g. it might be in an
- * unsupported format). If a renderable URL is needed for the file,
- * {@link renderableSourceURLs} should be used instead.
- *
- * The entries are keyed by file ID.
- */
private fileURLPromises = new Map<number, Promise<string>>();
- /**
- * An in-memory cache for {@link RenderableSourceURLs} for a file.
- *
- * These are saved as a result of invocation of
- * {@link renderableSourceURLs}, which goes one step beyond
- * {@link fileURLPromises}, and also attempts to convert the downloaded file
- * into a URL that the browser is likely to be able to render or play.
- *
- * The entries are keyed by file ID.
- */
private renderableSourceURLPromises = new Map<
number,
Promise<RenderableSourceURLs>
>();
- /**
- * A map from file ID to the progress (0-100%) of its active download (if
- * any).
- *
- * [Note: Tracking active file download progress in the UI]
- *
- * The download manager maintains a map of download progress for all files
- * which are being downloaded in a streaming manner (which is currently only
- * videos). The UI can observe this by using {@link useSyncExternalStore} in
- * combination with the {@link fileDownloadProgressSubscribe} and
- * {@link fileDownloadProgressSnapshot} methods of the download manager.
- */
private fileDownloadProgress = new Map<number, number>();
private fileDownloadProgressListeners: (() => void)[] = [];
@@ -192,9 +76,6 @@ export class DownloadManagerCore {
}
}
- /**
- * Reset the internal state of the download manager.
- */
logout() {
this.thumbnailURLPromises.clear();
this.fileURLPromises.clear();
@@ -203,9 +84,6 @@ export class DownloadManagerCore {
this.fileDownloadProgressListeners = [];
}
- /**
- * See: [Note: Tracking active file download progress in the UI]
- */
fileDownloadProgressSubscribe(onChange: () => void) {
this.fileDownloadProgressListeners.push(onChange);
return () => {
@@ -214,9 +92,6 @@ export class DownloadManagerCore {
};
}
- /**
- * See: [Note: Tracking active file download progress in the UI]
- */
fileDownloadProgressSnapshot() {
return this.fileDownloadProgress;
}
@@ -226,24 +101,7 @@ export class DownloadManagerCore {
this.fileDownloadProgressListeners.forEach((l) => l());
}
- /**
- * Resolves with an URL that points to the file's thumbnail.
- *
- * The thumbnail will be downloaded if needed (unless {@link cachedOnly} is
- * true). It will also be cached for subsequent fetches.
- *
- * The optional {@link cachedOnly} parameter can be set to indicate that
- * this is being called as part of a scroll, so the downloader should not
- * attempt to download the file but should instead fulfill the request from
- * the disk cache. This avoids an unbounded flurry of requests on scroll,
- * only downloading when the position has quiescized.
- *
- * The returned URL is actually an object URL, but it should not be revoked
- * since the download manager caches it for future use.
- *
- * If {@link cachedOnly} is false (the default), then this method will
- * indicate errors by throwing but will never return `undefined`.
- */
+ // Returned object URLs are cache-owned; callers must not revoke them.
async renderableThumbnailURL(
file: EnteFile,
cachedOnly = false,
@@ -259,7 +117,7 @@ export class DownloadManagerCore {
try {
thumb = await this.thumbnailURLPromises.get(file.id);
} catch (e) {
- // Do not cache a failed promise; allow follow-up calls to retry.
+ // Do not cache a failed promise; follow-up calls should retry.
this.thumbnailURLPromises.delete(file.id);
throw e;
}
@@ -273,20 +131,6 @@ export class DownloadManagerCore {
return thumb;
}
- /**
- * Returns the thumbnail data for a file, downloading it if needed.
- *
- * The data is cached on disk for subsequent fetches.
- *
- * @param file The {@link EnteFile} whose thumbnail we want.
- *
- * @param cachedOnly If true, then the thumbnail is not downloaded if it is
- * not already present in the disk cache.
- *
- * @returns The bytes of the thumbnail, as a {@link Uint8Array}. This method
- * can return `undefined` iff the thumbnail is not already cached, and
- * {@link cachedOnly} is set to `true`.
- */
async thumbnailData(
file: EnteFile,
cachedOnly = false,
@@ -311,13 +155,6 @@ export class DownloadManagerCore {
return decryptBlobBytes({ encryptedData, decryptionHeader }, file.key);
};
- /**
- * Return a URL (and associated metadata) that can be used to show the given
- * {@link file} within the app, converting its format (on the fly) if needed
- * (if possible).
- *
- * See the documentation of {@link RenderableSourceURLs} for more details.
- */
renderableSourceURLs = async (
file: EnteFile,
): Promise<RenderableSourceURLs> => {
@@ -340,12 +177,6 @@ export class DownloadManagerCore {
}
};
- /**
- * Return a blob to the file's contents, downloading it needed.
- *
- * This is a convenience abstraction over {@link fileStream} that converts
- * it into a {@link Blob}.
- */
async fileBlob(file: EnteFile, opts?: FileDownloadOpts) {
const _fileBlob = () =>
this.fileStream(file, opts).then((stream) =>
@@ -356,8 +187,7 @@ export class DownloadManagerCore {
try {
return await _fileBlob();
} catch (e) {
- // If the stream came from a cached object URL then retry once
- // to rule out issues with the cache.
+ // Retry without the cached object URL before surfacing the failure.
if (cachedURL) {
this.fileURLPromises.delete(file.id);
return _fileBlob();
@@ -367,18 +197,6 @@ export class DownloadManagerCore {
}
}
- /**
- * Return an stream to the file's contents, downloading it needed.
- *
- * Note that the results are not cached in-memory. That is, while the
- * request may be served from the existing item in the in-memory cache, if
- * it is not found and a download is required, that result will not be
- * cached for subsequent use.
- *
- * @param file The {@link EnteFile} whose data we want.
- *
- * @param opts Optional options to modify the download.
- */
async fileStream(
file: EnteFile,
opts?: FileDownloadOpts,
@@ -398,9 +216,6 @@ export class DownloadManagerCore {
return this.downloadFile(file, opts);
}
- /**
- * A private variant of {@link fileStream} that also caches the results.
- */
private async fileURLDownloadAndCacheIfNeeded(file: EnteFile) {
const cachedURL = this.fileURLPromises.get(file.id);
if (cachedURL) return cachedURL;
@@ -465,11 +280,9 @@ export class DownloadManagerCore {
return new ReadableStream({
pull: async (controller) => {
- // Each time pull is called, we want to enqueue at least once.
+ // Each pull must enqueue or close before returning.
let didEnqueue = false;
do {
- // done is a boolean and value is an Uint8Array. When done
- // is true value will be empty.
const { done, value } = await wrapErrors(() =>
reader.read(),
);
@@ -491,8 +304,7 @@ export class DownloadManagerCore {
data.set(new Uint8Array(value), leftoverBytes.length);
}
- // data.length might be a multiple of decryptionChunkSize,
- // and we might need multiple iterations to drain it all.
+ // A network read can contain several encrypted chunks.
while (data.length >= decryptionChunkSize) {
const decryptedData = await decryptStreamChunk(
data.slice(0, decryptionChunkSize),
@@ -504,8 +316,7 @@ export class DownloadManagerCore {
}
if (done) {
- // Send off the remaining bytes without waiting for a
- // full chunk, no more bytes are going to come.
+ // Only EOF proves that a short remainder is the final chunk.
if (data.length) {
const decryptedData = await decryptStreamChunk(
data,
@@ -513,15 +324,9 @@ export class DownloadManagerCore {
);
controller.enqueue(decryptedData);
}
- // Don't loop again even if we didn't enqueue.
didEnqueue = true;
controller.close();
} else {
- // Save it for the next pull.
-
- // See: [Note: Revisit some Node.js types errors post 22
- // upgrade]
- //
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
leftoverBytes = data;
@@ -578,22 +383,6 @@ export class DownloadManagerCore {
export const createDownloadManager = (transport: DownloadManagerTransport) =>
new DownloadManagerCore(transport);
-/**
- * A custom Error that is thrown if a download fails during network I/O.
- *
- * [Note: Identifying network related errors during download]
- *
- * We dealing with code that touches the network, we often don't specifically
- * care about the specific error - there is a lot that can go wrong when a
- * network is involved - but need to identify if an error was in the network
- * related phase of an action, since these are usually transient and can be
- * dealt with more softly than other errors.
- *
- * To that end, network related phases of download operations are wrapped in
- * catches that intercept the error and wrap it in our custom
- * {@link NetworkDownloadError} whose presence can be checked using the
- * {@link isNetworkDownloadError} predicate.
- */
export class NetworkDownloadError extends Error {
error: unknown;
@@ -602,8 +391,6 @@ export class NetworkDownloadError extends Error {
`NetworkDownloadError: ${e instanceof Error ? e.message : String(e)}`,
);
- // Cargo culted from
- // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
Error.captureStackTrace?.(this, NetworkDownloadError);
this.error = e;
@@ -613,20 +400,11 @@ export class NetworkDownloadError extends Error {
export const isNetworkDownloadError = (e: unknown) =>
e instanceof NetworkDownloadError;
-/**
- * A helper function to convert all rejections of the given promise {@link op}
- * into {@link NetworkDownloadError}s.
- */
const wrapErrors = <T>(op: () => Promise<T>) =>
op().catch((e: unknown) => {
throw new NetworkDownloadError(e);
});
-/**
- * Create and return a {@link RenderableSourceURLs} for the given {@link file},
- * where {@link originalFileURLPromise} is a promise that resolves with an
- * (object) URL to the contents of the original file.
- */
const createRenderableSourceURLs = async (
file: EnteFile,
originalFileURLPromise: Promise<string>,
diff --git a/web/packages/gallery/services/exif.ts b/web/packages/gallery/services/exif.ts
index f49107cda9..ea07bd3f48 100644
--- a/web/packages/gallery/services/exif.ts
+++ b/web/packages/gallery/services/exif.ts
@@ -6,36 +6,9 @@ import {
} from "ente-media/file-metadata";
import ExifReader from "exifreader";
-/**
- * Extract Exif and other metadata from the given file.
- *
- * [Note: Exif]
- *
- * Exif is a standard for metadata embedded in photos. Exif tags arise from the
- * TIFF specification but now can be found in other file formats, notably JPG,
- * PNG, AVI, MOV, TIFF-based RAW images (and TIFF itself)
- *
- * The standard uses "Exif" (not "EXIF") to refer to itself. We do the same.
- *
- * Exif is now commonly used as a synedoche for all forms of metadata that gets
- * embedded in a file, and this is also how we use the term. So these functions
- * extract and operate on not just Exif tags, but also XMP (XML metadata
- * embedded in images) and IPTC (another metadat standard) tags.
- *
- * A list for metadata tags can be found in exiftool's documentation:
- * https://exiftool.org/TagNames
- *
- * The library we use is https://github.com/mattiasw/ExifReader.
- */
export const extractExif = async (file: File) =>
await extractRawExif(file).then(parseExif);
-/**
- * Parse an already extracted {@link RawExifTags}.
- *
- * See: {@link extractExif}. This function does just the parsing step, for use
- * when we've already extracted the raw data.
- */
export const parseExif = (tags: RawExifTags) => {
const location = parseLocation(tags);
const creationDate = parseCreationDate(tags);
@@ -52,13 +25,6 @@ export const parseExif = (tags: RawExifTags) => {
return metadata;
};
-/**
- * Parse GPS location from the metadata embedded in the file.
- *
- * - If a location is returned, then both latitude and longitude will be
- * defined.
- * - NaNs are ignored, and treated as if they are not defined.
- */
const parseLocation = (tags: RawExifTags) => {
const latitude = tags.gps?.Latitude;
const longitude = tags.gps?.Longitude;
@@ -69,28 +35,12 @@ const parseLocation = (tags: RawExifTags) => {
return { latitude, longitude };
};
-/**
- * Parse a single "best" creation date for an image from the metadata embedded
- * in the file.
- *
- * A file has multiple types of metadata, and each of these has multiple types
- * of dates, so we use some an a heuristic ordering (based on experience with
- * the photos we find out in the wild) to pick a "best" date.
- */
const parseCreationDate = (tags: RawExifTags) => {
const { DateTimeOriginal, DateTimeDigitized, MetadataDate, DateTime } =
parseDates(tags);
return DateTimeOriginal ?? DateTimeDigitized ?? MetadataDate ?? DateTime;
};
-/**
- * Dates extracted from the Exif and other metadata embedded in a file.
- *
- * These are the dates corresponding to the various options we show to the user
- * for the "Fix date" functionality. These don't come solely from the Exif but
- * from all forms of metadata we support (Exif, XMP, IPTC). They roughly
- * correspond to the three Exif DateTime* tags, and the XMP MetadataDate tag.
- */
interface ParsedExifDates {
DateTimeOriginal: ParsedMetadataDate | undefined;
DateTimeDigitized: ParsedMetadataDate | undefined;
@@ -98,26 +48,12 @@ interface ParsedExifDates {
MetadataDate: ParsedMetadataDate | undefined;
}
-/**
- * Extract dates from Exif and other metadata for the given file.
- */
export const extractExifDates = (file: File): Promise<ParsedExifDates> =>
extractRawExif(file).then(parseDates);
-/**
- * Parse all date related fields from the metadata embedded in the file,
- * grouping them into chunks that somewhat reflect the Exif ontology.
- */
const parseDates = (tags: RawExifTags) => {
- // Ignore dates whose epoch is 0.
- //
- // Some customers (not sure how prevalent this is) reported photos with Exif
- // dates set to "0000:00:00 00:00:00". Ignore any date whose timestamp is 0
- // so that we try with a subsequent (possibly correct) date in the sequence.
- //
- // Filter out a known corrupted date value, "4501:01:01 00:00:00".
- // Certain devices default to this bogus timestamp, so skip it to allow other dates.
const valid = (d: ParsedMetadataDate | undefined) => {
+ // Real files use epoch zero and year 4501 as corrupt sentinel dates.
if (!d?.timestamp) return undefined;
if (d.dateTime === "4501-01-01T00:00:00.000") return undefined;
return d;
@@ -143,76 +79,6 @@ const parseDates = (tags: RawExifTags) => {
};
};
-/**
- * Parse a date from an Exif date and offset tag combination.
- *
- * @param tags Metadata tags associated with a file.
- *
- * @param dateTag The name of the date tag to use.
- *
- * @param offsetTag The name of the offset tag corresponding to {@link dateTag}.
- *
- * @returns a {@link Date} (UTC epoch milliseconds).
- *
- * [Note: Exif dates]
- *
- * The most important bit we usually wish out of Exif is the date and time when
- * the photo was taken. The Exif specification has the following tags related to
- * photo's date:
- *
- * - DateTimeOriginal
- * - DateTimeDigitized (aka "CreateDate")
- * - DateTime (aka "ModifyDate")
- *
- * DateTimeOriginal is meant to signify best when the original image was taken,
- * and we use it as the photo's creation date whenever it is present. If not, we
- * fallback to DateTimeDigitized or DateTime (in that order).
- *
- * Each of these is a string of the format
- *
- * YYYY:MM:DD HH:mm:ss
- *
- * where
- *
- * YYYY 4 digit (zero padded) year
- * MM 2 digit (zero padded) month, with Jan as 01 and Dec as 12.
- * DD 2 digit (zero padded) day of the month (1 to 31)
- * HH 2 digit (zero padded) hours since midnight (00 to 23)
- * mm 2 digit (zero padded) minutes (00 to 59)
- * ss 2 digit (zero padded) seconds (00 to 59)
- *
- * Additionally (and optionally), there are three SubSecTime* tags that provide
- * the fractional seconds (one for each of the above):
- *
- * - SubSecTimeOriginal
- * - SubSecTimeDigitized
- * - SubSecTime
- *
- * Each of which is a string specifying the fractional digits.
- *
- * The dates are all in the local time of the place where the photo was taken.
- * To convert these to UTC, we also need to know the offset from UTC of that
- * local time. This is provided by the three OffsetTime* tags (one for each of
- * the above):
- *
- * - OffsetTimeOriginal
- * - OffsetTimeDigitized
- * - OffsetTime
- *
- * Each of these is a string of the format
- *
- * ±HH:mm
- *
- * denoting the signed hour and minute offset from UTC.
- *
- * Note that these OffsetTime* tags are relatively new additions (prior to
- * smartphones, cameras did not have a good way of knowing their TZ), and most
- * old photos will not have this information. In such cases, we assume that
- * these photos are in the local time where this code is running. This is
- * manifestly going to be incorrect in some cases, but it is a better assumption
- * than assuming UTC, which, while deterministic, is going to incorrect in an
- * overwhelming majority of cases.
- */
const parseExifDates = ({ exif }: RawExifTags) => ({
DateTimeOriginal: parseExifDate(
exif?.DateTimeOriginal,
@@ -238,18 +104,7 @@ const parseExifDate = (
const [subSecString] = subSecTag?.value ?? [];
const [offsetString] = offsetTag?.value ?? [];
- // Perform minor syntactic changes to the Exif date, and add the optional
- // offset, to construct a string in the Javascript date time string format.
- // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format
- //
- // YYYY:MM:DD HH:mm:ss±HH:mm
- // YYYY-MM-DDTHH:mm:ss±HH:mm
- //
- // When the offset string is missing, the date time is interpreted as local
- // time. This is the behaviour we want.
- //
- // For details see [Note: Exif dates]
-
+ // Without an offset, Date intentionally interprets the camera time as local.
return parseMetadataDate(
dateString.replace(":", "-").replace(":", "-").replace(" ", "T") +
(subSecString ? "." + subSecString : "") +
@@ -257,47 +112,16 @@ const parseExifDate = (
);
};
-/**
- * Parse date related tags from XMP.
- *
- * The XMP information in the file can have the date related information in tags
- * spread across multiple namespaces.
- *
- * For a list of XMP tags, see https://exiftool.org/TagNames/XMP.html.
- */
const parseXMPDates = ({ xmp }: RawExifTags) => ({
- /* XMP namespace is indicated for each group */
- // exif:
DateTimeOriginal: parseXMPDate(xmp?.DateTimeOriginal),
DateTimeDigitized: parseXMPDate(xmp?.DateTimeDigitized),
- // exif: or tiff:
DateTime: parseXMPDate(xmp?.DateTime),
- // xmp:
CreateDate: parseXMPDate(xmp?.CreateDate),
ModifyDate: parseXMPDate(xmp?.ModifyDate),
MetadataDate: parseXMPDate(xmp?.MetadataDate),
- // photoshop:
DateCreated: parseXMPDate(xmp?.DateCreated),
});
-/**
- * Parse an XMP date tag.
- *
- * [Note: XMP dates]
- *
- * XMP dates use a format same as the ISO-8601 format that is used by JavaScript
- * as its date time string format.
- *
- * YYYY-MM-DDThh:mm:ss.sTZD
- *
- * The main difference being, unlike JavaScript, all of the above components
- * except YYYY are optional. In practice, browsers gracefully handle these
- * scenarios, so we can directly use the JavaScript date constructor.
- *
- * References:
- * - https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#date-value-type
- * - https://developer.adobe.com/xmp/docs/XMPNamespaces/XMPDataTypes/#date
- */
const parseXMPDate = (xmpTag: ExifReader.XmpTag | undefined) => {
if (!xmpTag) return undefined;
const s = xmpTag.value;
@@ -306,9 +130,6 @@ const parseXMPDate = (xmpTag: ExifReader.XmpTag | undefined) => {
return parseMetadataDate(s);
};
-/**
- * Parse date related tags from IPTC.
- */
const parseIPTCDates = ({ iptc }: RawExifTags) => ({
DateTimeOriginal: parseIPTCDate(
iptc?.["Date Created"],
@@ -320,47 +141,10 @@ const parseIPTCDates = ({ iptc }: RawExifTags) => ({
),
});
-/**
- * Parse an IPTC date tag.
- *
- * [Note: IPTC dates]
- *
- * IPTC date time values are split across two tag:
- *
- * - A tag containing the date as as 8 digit number of the form `YYYYMMDD`.
- *
- * - A tag containing the time as an 11 character string of the form
- * `HHMMSS±HHMM`.
- *
- * They lack separators, but together these tags are meant to encode the same
- * information as the ISO 8601 date format (that XMP and JavaScript also use).
- *
- * Reference:
- * - http://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf
- *
- * ---
- *
- * @param dateTag The tag containing the date part of the date.
- *
- * @param timeTag The tag containing the time part of the date.
- */
const parseIPTCDate = (
dateTag: ExifReader.NumberArrayTag | undefined,
timeTag: ExifReader.NumberArrayTag | undefined,
) => {
- // The library we use (ExifReader) parses them into a usable representation,
- // which we can use directly. Some notes:
- //
- // - There are currently no separate TypeScript types for the IPTC tags, and
- // instead they are listed as part of the ExifTags.
- //
- // - For the date, whenever possible ExifReader parses the raw data into a
- // description of the form 'YYYY-MM-DD' (See `getCreationDate` in its
- // source code).
- //
- // - For the time, whenever possible ExifReader parses the raw data into a
- // description either of the form 'HH:mm:ss` or `HH:mm:ss±HH:mm` (See
- // `getCreationTime` in its source code).
if (!dateTag) return undefined;
let s = dateTag.description;
@@ -369,17 +153,11 @@ const parseIPTCDate = (
return parseMetadataDate(s);
};
-/**
- * Parse the width and height of the image from the metadata embedded in the
- * file, taking into account any orientation tags that are also present.
- */
const parseDimensions = (tags: RawExifTags) => {
- // Go through all possibilities in order, returning the first pair with both
- // the width and height defined, and non-zero.
-
const pair = (w: number | undefined, h: number | undefined) =>
w && h ? { width: w, height: h } : undefined;
+ // Orientations 5-8 swap the displayed width and height.
const shouldSwapForExifOrientation = (orientation: number | undefined) => {
switch (orientation) {
case 5:
@@ -407,8 +185,6 @@ const parseDimensions = (tags: RawExifTags) => {
}
};
- // 1. Use the width and height from the file itself (e.g. JPEG data).
-
let wh =
pair(
tags.file?.["Image Width"]?.value,
@@ -424,9 +200,6 @@ const parseDimensions = (tags: RawExifTags) => {
) ??
pair(tags.riff?.ImageWidth?.value, tags.riff?.ImageHeight?.value);
if (wh) {
- // The dimensions read from the file headers can still correspond to
- // the un-rotated pixel matrix. For orientations 5-8, we need to swap
- // them to represent the display dimensions used by masonry.
const shouldSwap =
shouldSwapForExifOrientation(tags.exif?.Orientation?.value) ||
(tags.exif?.Orientation?.value == undefined &&
@@ -434,32 +207,13 @@ const parseDimensions = (tags: RawExifTags) => {
return shouldSwap ? { width: wh.height, height: wh.width } : wh;
}
- // 2. Exif dimensions, taking Orientation also into account if needed.
-
wh =
- pair(
- tags.exif?.ImageWidth?.value,
- /* The Exif spec calls it ImageLength, not ImageHeight. */
- tags.exif?.ImageLength?.value,
- ) ??
+ pair(tags.exif?.ImageWidth?.value, tags.exif?.ImageLength?.value) ??
pair(
tags.exif?.PixelXDimension?.value,
tags.exif?.PixelYDimension?.value,
);
if (wh) {
- // Exif Orientation tags can have the following values:
- //
- // 1 = Horizontal (normal)
- // 2 = Mirror horizontal
- // 3 = Rotate 180
- // 4 = Mirror vertical
- // 5 = Mirror horizontal and rotate 270 CW
- // 6 = Rotate 90 CW
- // 7 = Mirror horizontal and rotate 90 CW
- // 8 = Rotate 270 CW
- //
- // Ref: https://exiftool.org/TagNames/EXIF.html
-
const swap = shouldSwapForExifOrientation(
tags.exif?.Orientation?.value,
);
@@ -467,8 +221,6 @@ const parseDimensions = (tags: RawExifTags) => {
return swap ? { width: wh.height, height: wh.width } : wh;
}
- // 3. XMP dimensions, taking Orientation also into account if needed.
-
wh =
pair(
parseXMPNum(tags.xmp?.ImageWidth),
@@ -480,11 +232,6 @@ const parseDimensions = (tags: RawExifTags) => {
);
if (wh) {
- // The Orientation present in XMP (as a TIFF tag) also uses the same
- // constants as Exif above.
- //
- // Ref: https://exiftool.org/TagNames/XMP.html
-
const swap = shouldSwapForXMPOrientation(tags.xmp?.Orientation?.value);
return swap ? { width: wh.height, height: wh.width } : wh;
@@ -493,9 +240,6 @@ const parseDimensions = (tags: RawExifTags) => {
return undefined;
};
-/**
- * Try to parse the given XMP tag as a number.
- */
const parseXMPNum = (xmpTag: ExifReader.XmpTag | undefined) => {
if (!xmpTag) return undefined;
const s = xmpTag.value;
@@ -510,123 +254,30 @@ export type RawExifTags = Omit<ExifReader.ExpandedTags, "Thumbnail" | "xmp"> & {
xmp?: ExifReader.XmpTags;
};
-/**
- * Extract "raw" exif and other metadata from the given file.
- *
- * @param blob A {@link Blob} containing the data of an {@link EnteFile}.
- *
- * @return A JSON object containing the raw exif and other metadata that was
- * found in the given {@link blob}.
- *
- * ---
- *
- * [Note: Defining "raw" Exif]
- *
- * We wish for a canonical "raw" JSON representing all the Exif data associated
- * with a file. This goal is tricky to achieve because:
- *
- * - While Exif itself is a standard, with a standard set of tags (a numeric
- * id), in practice vendors can use tags more than what are currently listed
- * in the standard.
- *
- * - We're not just interested in Exif tags, but rather at all forms of metadata
- * (e.g. XMP, IPTC) that can be embedded in a file.
- *
- * By default, the library we use (ExifReader) returns a merged object
- * containing all tags it understands from all forms of metadata that it knows
- * about.
- *
- * Since it only returns the tags it understands, it acts an an implicit
- * whitelist. This implicit whitelist behaviour can be turned off by specifying
- * the `includeUnknown` flag, but for our case it is useful since it acts as a
- * safeguard against extracting an unbounded amounts of data (for example, there
- * is an Exif tag for thumbnails. While we specifically filter out that
- * particular tag, it is not hard to imagine some other unforeseen vendor
- * specific tag containing a similarly large amounts of embedded data).
- *
- * So we keep the default behaviour of returning only the tags that the library
- * knows about. Luckily for us, it returns all the XMP tags even if this flag is
- * specified, and that is one place where we'd like unknown tags so that we can
- * selectively start adding support for them.
- *
- * The other default behaviour, of returning a merged object, is a bit more
- * problematic for our use case, since it loses information. Thus, to keep
- * things more deterministic, we specify the `expanded` flag which returns all
- * these different forms of metadata separately.
- *
- * That's for the tags we get. Now to their contents. Generally for each tag
- * (but not for always), we get an entry with an "id", "value" (e.g. the raw
- * bytes), and a "description" (which is the raw data parsed to a form that is
- * more usable). Technically speaking, the value is the raw data we want, but in
- * some cases, the availability of a pre-parsed description will be convenient
- * too. So we don't prune anything, and keep all three.
- *
- * All this means we end up with a JSON whose exact structure is tied to the
- * library we're using (ExifReader), or even its version (the library reserves
- * the right to change the formatting of the "description" fields in minor
- * version updates).
- *
- * So this is not really "raw" Exif. But with that caveat out of the way,
- * practically this should be raw enough given the tradeoffs mentioned above,
- * while allowing us to consume this JSON in arbitrary clients without needing
- * to know about ExifReader specifically.
- */
export const extractRawExif = async (blob: Blob): Promise<RawExifTags> => {
- // The browser's DOMParser is not available in web workers. So if this
- // function gets called in from a web worker, then it would not be able to
- // parse XMP tags.
- //
- // There is a way around this problem, by also installing ExifReader's
- // optional peer dependency "@xmldom/xmldom". But since we currently have no
- // use case for calling this code in a web worker, we just abort immediately
- // to let future us know that we need to install it.
+ // ExifReader needs DOMParser for XMP; its optional worker polyfill is absent.
if (inWorker())
throw new Error("DOMParser is not available in web workers");
+ // Preserve namespaces, but do not include unknown tags with unbounded payloads.
const tags = await ExifReader.load(await blob.arrayBuffer(), {
async: true,
expanded: true,
});
- // Remove the embedded thumbnail (if any).
+ // Never retain embedded image payloads in metadata JSON.
delete tags.Thumbnail;
delete tags.exif?.Thumbnail;
- // Remove the embedded MPF images (if any).
- //
- // The TypeScript definition is out of data and doesn't include the top
- // level 'mpf', so we need to cast. From the source:
- //
- // > The images can be accessed by the tags.Images array (tags.mpf.Images if
- // > using expanded: true).
- //
+ // MPF entries can contain more embedded images.
delete (tags as Record<string, unknown>).mpf;
- // Remove the raw XMP (if any).
- //
- // The `includeUnknown` flag does not have any effect on the XMP parser, so
- // we already get all the key value pairs in the XMP as part of the "xmp"
- // object, retaining the raw string is unnecessary.
- //
- // We need to cast to remove the non-optional _raw property. Be aware that
- // this means that from this point onwards, the TypeScript type is out of
- // sync with the actual value (TypeScript type says _raw is always present,
- // while the actual value doesn't have it).
+ // Parsed XMP entries already retain the useful data.
delete (tags.xmp as Partial<typeof tags.xmp>)?._raw;
return tags;
};
-/**
- * Return a number from a raw Exif tag value.
- *
- * Some numeric Exif values are stored as arrays of two numbers [p, q]
- * representing a rational number p/q. ExifReader usually converts this and for
- * us, but not always.
- *
- * This function takes such potentially ambiguous (already converted or not)
- * values and returns a number.
- */
export const tagNumericValue = (
tag: ExifReader.NumberTag | ExifReader.NumberArrayTag,
) => {
@@ -643,24 +294,7 @@ const parseCamera = (tags: RawExifTags) => {
return { make, model };
};
-/**
- * Parse the description for an image from the metadata embedded in the file.
- *
- * This function will read the description from the following fields, in order:
- *
- * 1. XMP-dc:description
- * 2. IPTC | Caption/Abstract (120)
- * 3. EXIF IFD0 | 0x010e | ImageDescription
- *
- * For an overview of why this ordering was chosen, see
- * https://github.com/ente/ente/discussions/3857#discussioncomment-11764990
- */
const parseDescription = (tags: RawExifTags) =>
- // While the TypeScript tags for these three fields are varying (The XMP one
- // doesn't have a static type, the IPTC one is marked as a number array, and
- // the Exif one is a string array), for all three of these, the ExifReader
- // description property (not related to the image "description" in the sense
- // of this function) holds the singular string we're interested in.
tags.xmp?.description?.description ??
tags.iptc?.["Caption/Abstract"]?.description ??
tags.exif?.ImageDescription?.description;
diff --git a/web/packages/gallery/services/file-data.ts b/web/packages/gallery/services/file-data.ts
index ce6bf683da..3bf53e1e39 100644
--- a/web/packages/gallery/services/file-data.ts
+++ b/web/packages/gallery/services/file-data.ts
@@ -16,88 +16,19 @@ import type { EnteFile } from "ente-media/file";
import { nullToUndefined } from "ente-utils/transform";
import { z } from "zod";
-/**
- * [Note: File data APIs]
- *
- * Remote provides some APIs that talk in terms of "file data", which refers to
- * all the files (original or derived) associated with an {@link EnteFile}.
- *
- * For example, for each original image that the user uploads, there will be an
- * associated thumbnail file, potentially one or more preview files (optimized
- * for size or compatibility across devices), various ML embeddings generated
- * for that file, and possibly more such files in the future.
- *
- * There are specialized APIs for fetching and uploading the originals and the
- * thumbnails. But for the other associated data, we can use the file data APIs.
- */
-type FileDataType =
- | "mldata" /* See: [Note: "mldata" format] */
- | "vid_preview" /* See: [Note: Video playlist and preview] */;
+type FileDataType = "mldata" | "vid_preview";
const RemoteFileData = z.object({
- /**
- * The ID of the {@link EnteFile} with which this file data is associated.
- */
fileID: z.number(),
- /**
- * Base64 representation of the encrypted data. Its plaintext contents will
- * be specific to each file data type.
- */
encryptedData: z.string(),
- /**
- * Base64 representation of the header that should be passed when decrypting
- * {@link encryptedData}. See the {@link decryptMetadata} function in the
- * crypto layer.
- */
decryptionHeader: z.string(),
- /**
- * The epoch microseconds when this file data entry was last upserted.
- *
- * [Note: PUT "mldata" version check]
- *
- * When PUT-ting mldata onto remote, the client is expected to pass the
- * updated at of the existing {@link RemoteFileData} which it is updating
- * (this field), or 0 if the client is creating a new entity.
- *
- * This allows remote to detect and reject cases where the client is trying
- * to overwrite a version it hasn't yet pulled.
- *
- * About the optionality of this field: Newer museums are expected to always
- * provide the {@link updatedAt} in the response, but for ease of self
- * hosters we don't take a hard dependency on the latest museum and instead
- * allow this field to be optional. When it is not present, effectively
- * we'll pass 0 as {@link lastUpdatedAt} in the "mldata" PUT API call, but
- * since it's an old museum it'll anyway ignore it.
- *
- * > This note was added May 2025, and the optionality can be removed in a
- * > few months when museums should've updated (tag: Migration).
- */
+ // Optional only for older self-hosted museums.
updatedAt: z.number().nullish().transform(nullToUndefined),
});
type RemoteFileData = z.infer<typeof RemoteFileData>;
-/**
- * Fetch file data of a particular type for the given list of files.
- *
- * @param type The {@link FileDataType} which we want.
- *
- * @param fileIDs The ids of the files for which we want the file data.
- *
- * @returns a list of {@link RemoteFileData} items for the files which had file
- * data for the given type, and that remote was able to successfully retrieve.
- *
- * The order of this list is arbitrary, and the caller should use the
- * {@link fileID} present within the {@link RemoteFileData} to associate an item
- * in the result back to a file instead of relying on the order or count of
- * items in the result.
- *
- * In rare cases (issues with the upstream object storage), it is possible for
- * remote to not return entries for a particular file even though it has
- * associated data of that type. Such skipped entries are mentioned in the
- * payload, but we don't parse that information currently since the higher
- * levels of our code that use this function handle such rare skips gracefully.
- */
+// Results are sparse and unordered; associate them by fileID.
export const fetchFilesData = async (
type: FileDataType,
fileIDs: number[],
@@ -112,19 +43,6 @@ export const fetchFilesData = async (
.data;
};
-/**
- * A variant of {@link fetchFilesData} that fetches data for a single file.
- *
- * Unlike {@link fetchFilesData}, this uses a HTTP GET request.
- *
- * Returns `undefined` if no file data of the given type has been uploaded for
- * this file yet (e.g. if type was "vid_preview", this would indicate that a
- * video preview has been generated for this file yet).
- *
- * @param publicAlbumsCredentials Credentials to use when we are running in the
- * context of the public albums app. If these are not specified, then the
- * credentials of the logged in user are used.
- */
export const fetchFileData = async (
type: FileDataType,
fileID: number,
@@ -134,8 +52,6 @@ export const fetchFileData = async (
const params = new URLSearchParams({
type,
fileID: fileID.toString(),
- // Ask museum to respond with 204 instead of 404 if no playlist exists
- // for the given file.
preferNoContent: "true",
});
@@ -160,94 +76,25 @@ export const fetchFileData = async (
}
if (res.status == 204) return undefined;
- // We're passing `preferNoContent` so the expected response is 204, but this
- // might be a self hoster running an older museum that does not recognize
- // that flag, so retain the old behavior. This fallback can be removed in a
- // few months (tag: Migration, note added May 2025).
+ // Older museums ignore preferNoContent and still return 404.
if (res.status == 404) return undefined;
ensureOk(res);
return z.object({ data: RemoteFileData }).parse(await res.json()).data;
};
-/**
- * An entry in the response to the `/files/data/status-diff`. The actual
- * structure has more fields, there are just the fields we are interested in.
- */
const RemoteFDStatus = z.object({
- /**
- * The ID of the file whose file data we're querying.
- */
fileID: z.number(),
- /**
- * Expected to be one of {@link FileDataType}
- */
type: z.string(),
- /**
- * `true` if the file data has been deleted.
- *
- * This can be true in the in-progress partial deletion case, which the file
- * data deletion has been processed but the file deletion has not yet been
- * processed.
- */
isDeleted: z.boolean(),
- /**
- * The epoch microseconds when this file data entry was added or updated.
- */
updatedAt: z.number(),
});
-/**
- * A paginated part of the result set sent by remote during
- * {@link syncUpdatedFileDataFileIDs}.
- */
export interface UpdatedFileDataFileIDsPage {
- /**
- * The IDs of files for which a file data entry has been created or updated.
- */
fileIDs: Set<number>;
- /**
- * The latest updatedAt (epoch microseconds) time obtained from remote in
- * this batch being fetched (from amongst all of the files in the batch, not
- * just those that were filtered to be part of {@link fileIDs}).
- */
lastUpdatedAt: number;
}
-/**
- * Fetch the IDs of files for which new file data entries of the given
- * {@link type} have been created or updated since the given {@link sinceTime}.
- *
- * The interaction with remote is paginated, with the {@link onPage} callback
- * being called as each page of new data is received.
- *
- * @param type The {@link FileDataType} for which we want to check for creation
- * or updates.
- *
- * @param lastUpdatedAt Epoch microseconds. This is used to ask remote to
- * provide us only entries whose {@link updatedAt} is more than the given value.
- * Set this to zero to start from the beginning.
- *
- * @param onPage A callback invoked for each page of results received from
- * remote. It is passed the fileIDs received in the batch under consideration,
- * and the largest of the updated time for all entries (irrespective of
- * {@link type}) in that batch.
- *
- * ----
- *
- * [Note: Pruning stale status-diff entries]
- *
- * Unlike other "diff" APIs, the diff API used here won't return tombstone
- * entries for deleted files. This is not a problem because there are no current
- * cases where existing playlists or ML indexes get deleted (unless the
- * underlying file is deleted). See: [Note: Caching HLS playlist data].
- *
- * Note that the "/files/data/status-diff" includes entries for files that are
- * in trash. This means that, while not a practical problem (because it's just
- * numeric ids), the number of fileIDs we store locally can grow unbounded as
- * files move to trash and then get deleted. So to prune them, we also add a
- * hook to the /trash/v2/diff processing, and prune any locally saved file IDs
- * which have been deleted from trash.
- */
+// Underlying file deletions have no tombstones here; trash sync prunes saved IDs.
export const syncUpdatedFileDataFileIDs = async (
type: FileDataType,
lastUpdatedAt: number,
@@ -267,9 +114,6 @@ export const syncUpdatedFileDataFileIDs = async (
const fileIDs = new Set<number>();
for (const fd of diff) {
lastUpdatedAt = Math.max(lastUpdatedAt, fd.updatedAt);
- // While we could prune isDeleted entries here, we can also rely
- // on the pruning that happens when the trash gets synced. See:
- // [Note: Pruning stale status-diff entries]
if (fd.type == type && !fd.isDeleted) {
fileIDs.add(fd.fileID);
}
@@ -281,23 +125,7 @@ export const syncUpdatedFileDataFileIDs = async (
}
};
-/**
- * Upload file data associated with the given file to remote.
- *
- * This function will save or update the given data as the latest file data of
- * {@link type} associated with the given {@link file}. The data will be
- * end-to-end encrypted using the given {@link file}'s key before uploading.
- *
- * @param file {@link EnteFile} which this data is associated with.
- *
- * @param type The {@link FileDataType} which we are uploading.
- *
- * @param data The binary data to upload. The exact contents of the data are
- * {@link type} specific.
- *
- * @param lastUpdatedAt The {@link updatedAt} of the {@link RemoteFileData}
- * which we are updating, or 0 to indicate a new entity.
- */
+// lastUpdatedAt prevents overwriting remote data newer than the caller's pull.
export const putFileData = async (
file: EnteFile,
type: FileDataType,
@@ -323,47 +151,7 @@ export const putFileData = async (
ensureOk(res);
};
-/**
- * Fetch the preview file data the given file.
- *
- * @param type The {@link FileDataType} which we want.
- *
- * @param fileIDs The id of the files for which we want the file preview data.
- *
- * @param publicAlbumsCredentials Credentials to use when we are running in the
- * context of the public albums app. If these are not specified, then the
- * credentials of the logged in user are used.
- *
- * @returns the (pre-signed) URL to the preview data, or undefined if there is
- * not preview data of the given type for the given file yet.
- *
- * [Note: File data vs file preview data]
- *
- * In museum's ontology, there is a distinction between two concepts:
- *
- * S3 metadata (museum term, the APIs call it "file data") is data that museum
- * uploads on behalf of the client. e.g.,
- *
- * - ML data.
- *
- * - Preview video playlist.
- *
- * S3 file data (museum term, the APIs call it "file preview data") is data that
- * a client itself uploads. e.g.,
- *
- * - The preview video itself.
- *
- * - Additional preview images.
- *
- * [Note: Video playlist and preview]
- *
- * For a streaming video, both these concepts are needed:
- *
- * - The encrypted HLS playlist is stored as "file data" of type "vid_preview",
- *
- * - The encrypted video chunks that the playlist refers to are stored as "file
- * preview data" of type "vid_preview".
- */
+// Museum stores playlists as file data and client-uploaded segments as preview data.
export const fetchFilePreviewData = async (
type: FileDataType,
fileID: number,
@@ -397,32 +185,6 @@ export const fetchFilePreviewData = async (
return z.object({ url: z.string() }).parse(await res.json()).url;
};
-/**
- * Update the video data associated with the given file to remote.
- *
- * Video data refers to two things:
- *
- * - The encrypted HLS playlist ("file data" of type "vid_preview").
- *
- * - The object ID of an (already uploaded) "file preview data" file containing
- * the video segments.
- *
- * This function is similar to {@link putFileData}, except it will save (or
- * update) both the playlist, and the reference to its associated segment file,
- * associated with the given {@link file}. The playlist data will be end-to-end
- * encrypted using the given {@link file}'s key before uploading.
- *
- * @param file {@link EnteFile} which this data is associated with.
- *
- * @param encryptedPlaylist The encrypted playlist data (along with the nonce
- * used during encryption).
- *
- * @param objectID Object ID of an already uploaded "file preview data" (see
- * {@link getFilePreviewDataUploadURL}).
- *
- * @param objectSize The size (in bytes) of the file corresponding to
- * {@link objectID}.
- */
export const putVideoData = async (
file: EnteFile,
encryptedPlaylist: EncryptedBlobB64,
diff --git a/web/packages/gallery/services/files-db.ts b/web/packages/gallery/services/files-db.ts
index 755863e7bb..f8d10175bc 100644
--- a/web/packages/gallery/services/files-db.ts
+++ b/web/packages/gallery/services/files-db.ts
@@ -1,50 +1,3 @@
-/**
- * @file
- *
- * [Note: Files DB]
- *
- * Prior to us using idb for accessing IndexedDB, we used localForage (another
- * IndexedDB library) for that purpose (See `docs/storage.md` for more context).
- *
- * Our use of localForage was (and is) limited to:
- *
- * - A single IndexedDB database named "ente-files" containing
- *
- * - A single table named "files"
- *
- * It stored more than files though - files, collections, trash, their
- * corresponding sync times, and other bits and bobs related to them.
- *
- * > Note: File contents themselves are not stored in IndexedDB, only
- * > {@link EnteFile}s.
- *
- * Since we've now switched to idb as our preferred IndexedDB library, the data
- * stored in this files table could be considered legacy in a sense. But such
- * would be an incorrect characterization - this code has no issues, and it
- * stores core data for us (files and collections are as core as it gets).
- *
- * So this table is not legacy or deprecated, and there is currently no strong
- * reason to migrate this data to another IndexedDB table (it works fine as it
- * is, really). However we do want to avoid adding more items here, and maybe
- * gradually move some of the "bits and bobs" elsewhere (e.g. KV DB).
- *
- * ---
- *
- * This file contains the common code and types. Application layer code should
- * usually be accessing the app specific files DB by importing the functions
- * from the following modules:
- *
- * - Photos app: `photos-fdb.ts`
- * - Public albums app: `public-albums-fdb.ts`
- *
- * Note that even though both of them refer to the same conceptual "files DB",
- * the actual storage is distinct since both the apps run on separate domains
- * and so have their separate IndexedDB storage and thus separate files tables.
- *
- * Still, the key names are distinct to reduce chances of confusion: the public
- * albums app stores data in keys prefixed with "public-".
- */
-
import { haveWindow } from "ente-base/env";
import log from "ente-base/log";
import {
@@ -71,6 +24,8 @@ import { nullishToEmpty, nullToUndefined } from "ente-utils/transform";
import localForage from "localforage";
import { z } from "zod";
+// This localForage table remains core metadata storage, not a legacy store.
+// Photos and public albums get separate origin-scoped instances.
if (haveWindow()) {
localForage.config({
name: "ente-files",
@@ -79,21 +34,8 @@ if (haveWindow()) {
});
}
-/**
- * Reexport localForage for use by (and only by):
- * - photos-fdb.ts
- * - public-albums-fdb.ts
- * - migration.ts
- */
export { localForage };
-/**
- * Return `true` if we can access IndexedDB.
- *
- * This is used as a pre-flight check, to notify the user if they're using a
- * browser or extension that is preventing the app from using IndexedDB (which
- * is necessary for local storage of collections and files metadata).
- */
export const canAccessIndexedDB = async () => {
try {
await localForage.ready();
@@ -104,30 +46,14 @@ export const canAccessIndexedDB = async () => {
}
};
-/**
- * Clear any data stored in files DB.
- *
- * This is meant to be called during the logout sequence.
- */
export const clearFilesDB = () => localForage.clear();
-/**
- * Return a Zod schema suitable for being used with the various magic metadata
- * fields of a file or a collection.
- */
const createMagicMetadataSchema = <T extends z.ZodType>(dataSchema: T) =>
z
.object({ version: z.number(), count: z.number(), data: dataSchema })
.nullish()
.transform(nullToUndefined);
-/**
- * Zod schema for a {@link Collection} stored in our local database.
- *
- * This is similar to {@link RemoteCollection}, but it differs in that it
- * contains the decrypted values instead of the encrypted data and nonce pairs.
- * There are also some other minor nullish transforms.
- */
const LocalCollection = z
.looseObject({
id: z.number(),
@@ -155,10 +81,7 @@ const LocalCollection = z
),
})
.transform((c) => {
- // Old data stored locally contained fields which are no longer needed.
- // Do some zod gymnastics to drop these when reading (so that they're
- // not written back the next time). This code was added June 2025,
- // 1.7.14-beta, and can be removed after a bit (tag: Migration).
+ // TODO: Remove this June 2025 local collection migration when obsolete.
const {
encryptedKey,
keyDecryptionNonce,
@@ -181,12 +104,6 @@ const LocalCollection = z
export const LocalCollections = z.array(LocalCollection);
-/**
- * Zod schema for a {@link EnteFile} stored in our local database.
- *
- * This is similar to {@link RemoteEnteFile}, but it differs in that it contains
- * the decrypted values instead of the encrypted data and nonce pairs.
- */
export const LocalEnteFile = z.looseObject({
id: z.number(),
collectionID: z.number(),
@@ -203,45 +120,11 @@ export const LocalEnteFile = z.looseObject({
export const LocalEnteFiles = z.array(LocalEnteFile);
-/**
- * Apply transformations when reading files from the DB.
- *
- * There are two parts to it -
- *
- * 1. the required part (patching old entries that might be present in the local
- * database),
- * 2. the optional part (removing some unused fields).
- *
- * Part 1 ---
- *
- * Transform metadata in legacy files that might be present in the local
- * database. Note that this will not be needed for files that are fetched
- * afresh, since the corresponding transform is already done during
- * {@link decryptRemoteFile}; this is only for handling potentially items that
- * might've been already present locally.
- *
- * Part 2 ---
- *
- * Remove unused fields from the file objects when reading them.
- *
- * This is similar to the transformation we perform when reading collections
- * from the database, to discard fields that are no longer forwarded when we
- * parse the remote object, and thus will not be present in the local DB either
- * when going forward. They might be present for the existing entries in DB
- * though, which is why these functions are needed.
- *
- * However, since unlike collections, we don't route the files through Zod when
- * reading. So instead we do it using this function. Effectively, the end result
- * should be the same. In any case, doing this cleanup has no functional impact.
- *
- * Both parts added June 2025, 1.7.14-beta, prune eventually (tag: Migration).
- */
+// TODO: Remove this June 2025 local file migration when obsolete.
export const transformFilesIfNeeded = (files: EnteFile[]) =>
isFilesTransformNeeded(files) ? files.map(transformFile) : files;
-// Preflight check to turn the potentially non-trivial overhead (~50ms for 200k
-// files if everything runs through transformFile) into an effective no-op
-// (2-3ms) for the majority happy paths which don't need any transform.
+// Avoid running the per-file migration across 200k clean records.
const isFilesTransformNeeded = (
files: (EnteFile & { isDeleted?: unknown })[],
) =>
@@ -261,10 +144,6 @@ const transformFile = (file: EnteFile & { isDeleted?: unknown }) => {
...rest
} = file;
ignore(isDeleted);
- // We live with the cast here since this migration code should eventually be
- // removed. The cast is needed because in the original context,
- // transformDecryptedMetadataJSON acts on arbitrary JSON objects that have
- // not yet been validated to be of type FileMetadata.
const metadata = transformDecryptedMetadataJSON(
file.id,
origMetadata,
@@ -284,11 +163,4 @@ const transformFile = (file: EnteFile & { isDeleted?: unknown }) => {
} satisfies EnteFile;
};
-/**
- * A convenience Zod schema for a nullish number, with `null`s being transformed
- * to `undefined`.
- *
- * This is convenient when parsing the various timestamps we keep corresponding
- * to top level keys in the files DB. Don't use elsewhere!
- */
export const LocalTimestamp = z.number().nullish().transform(nullToUndefined);
diff --git a/web/packages/gallery/services/upload/index.ts b/web/packages/gallery/services/upload/index.ts
index 8714e0b9f2..4edcf03463 100644
--- a/web/packages/gallery/services/upload/index.ts
+++ b/web/packages/gallery/services/upload/index.ts
@@ -8,177 +8,34 @@ import type { EnteFile } from "ente-media/file";
import { tryParseTakeoutAlbumNameMetadataJSON } from "./metadata-json";
import type { ExternalParsedMetadata } from "./upload-service";
-/**
- * Internal in-memory state shared by the functions in this module.
- *
- * This entire object will be reset on logout.
- */
class UploadState {
- /**
- * `true` if the workers should be disabled for uploads.
- */
shouldDisableCFUploadProxy = false;
- /**
- * `true` if uploads should include checksum metadata.
- */
checksumProtectedUploadsEnabled = false;
}
-/** State shared by the functions in this module. See {@link UploadState}. */
let _state = new UploadState();
-/**
- * Reset any internal state maintained by the module.
- *
- * This is primarily meant as a way for stateful apps (e.g. photos) to clear any
- * user specific state on logout.
- */
export const resetUploadState = () => {
_state = new UploadState();
};
-/**
- * An item to upload is one of the following:
- *
- * 1. [web | desktop] A file drag-and-dropped or selected by the user when we
- * are running in a web browser. This is the {@link File} case. There is one
- * special case when this can also happen when running in the context of our
- * desktop app - when the user edits an existing image.
- *
- * 2. [desktop] A file drag-and-dropped or selected by the user when we are
- * running in the context of our desktop app. In such cases, we also have the
- * absolute path of the file in the user's local file system. This is the
- * {@link FileAndPath} case.
- *
- * 3. [desktop] A file path programmatically requested by the desktop app. For
- * example, we might be resuming a previously interrupted upload after an app
- * restart (thus we no longer have access to the {@link File} from case 2).
- * Or we could be uploading a file this is in one of the folders the user has
- * asked us to watch for changes. This is the `string` case.
- *
- * 4. [desktop] A file within a zip file on the user's local file system. This
- * too is only possible when we are running in the context of our desktop
- * app. The user might have drag-and-dropped or selected a zip file, or it
- * might be a zip file that they'd previously selected but we now are
- * resuming an interrupted upload of. Either ways, what we have is a tuple
- * containing the (path to zip file, and the name of an entry within that zip
- * file). This is the {@link ZipItem} case.
- *
- * Case 1 is possible both when we're running in the web app and desktop app
- * (that said, usually it only happens for the web app; it'll only happen in
- * desktop in the special case when editing an image).
- *
- * Case 2, 3 and 4 are only possible when we're running in the desktop app.
- *
- * Also see: [Note: Reading a UploadItem].
- */
export type UploadItem = File | FileAndPath | string | ZipItem;
-/**
- * When we are running in the context of our desktop app, we have access to the
- * absolute path of {@link File} objects. This convenience type clubs these two
- * bits of information, saving us the need to query the path again and again
- * using the {@link getPathForFile} method of {@link Electron}.
- */
export interface FileAndPath {
file: File;
path: string;
}
-/**
- * The cases of {@link UploadItem} that apply when we're running in the context
- * of our desktop app, and the item that was uploaded has an associated file on
- * the user's file system with a known path.
- *
- * See also {@link TimestampedFileSystemUploadItem}.
- */
export type FileSystemUploadItem = Exclude<UploadItem, File>;
-/**
- * A {@link FileSystemUploadItem} augmented with the last modified time of the
- * corresponding file on disk.
- *
- * By keeping the last modified time, we can use it as a test of whether or not
- * the file on disk was modified since it was uploaded. Such an ability is
- * useful for tasks where there can be a arbitrary delay between when the file
- * was uploaded and when the file gets processed.
- *
- * See {@link toTimestampedDesktopUploadItem} for converting a
- * {@link FileSystemUploadItem} into a {@link TimestampedFileSystemUploadItem}
- * when running in the context of the desktop app.
- */
export interface TimestampedFileSystemUploadItem {
- /**
- * Information about the file system file which was uploaded to Ente.
- */
fsUploadItem: FileSystemUploadItem;
- /**
- * The last modified time (epoch milliseconds) of the file system file.
- */
lastModifiedMs: number;
}
-/**
- * An "path prefix"-like opaque string which can be used to disambiguate
- * distinct source {@link UploadItem}s with the same name that are meant to be
- * uploaded to the same destination Ente album.
- *
- * Th documentation of {@link UploadItem} describes the four cases that an
- * {@link UploadItem} can be. For each of these, we augment an
- * {@link UploadItem} with a prefix ("dirname") derived from its best "path":
- *
- * - Relative path or name in the case of web {@link File}s.
- *
- * - Absolute path in the case of desktop {@link File} or path or
- * {@link FileAndPath}.
- *
- * - Path within the zip file for desktop {@link ZipItem}s.
- *
- * Thus, this path should not be treated as an address that can be used to
- * retrieve the upload item, but rather as extra context that can help us
- * distinguish between items by their relative or path prefix when their file
- * names are the same and they're being uploaded to the same album.
- *
- * Consider the following hierarchy:
- *
- * Foo/2017/Album1/1.png
- * Foo/2017/Album1/1.png.json
- *
- * Foo/2020/Album1/1.png
- * Foo/2020/Album1/1.png.json
- *
- * If user uploads `Foo`, irrespective of if they select the "root" or "parent"
- * option {@link CollectionMapping} option, when matching the takeout, only the
- * Ente album is considered. So it will be undefined which JSON will get used,
- * and both PNG files will get the same JSON, not their file system siblings.
- *
- * In such cases, the path prefix of the item being uploaded can act as extra
- * context that can help us disambiguate and pick the sibling. Note how we don't
- * need the path prefix to be absolute or relative or even addressable, we just
- * need it as extra context that can help us disambiguate two items with
- * otherwise the same name and that are destined for the same Ente album.
- *
- * So for our example, the path prefixes will be
- *
- * Foo/2017/Album1/1.png "Foo/2017/Album1"
- * Foo/2017/Album1/1.png.json "Foo/2017/Album1"
- *
- * Foo/2020/Album1/1.png "Foo/2020/Album1"
- * Foo/2020/Album1/1.png.json "Foo/2020/Album1"
- *
- * And can thus be used to associate the correct metadata JSON with the
- * corresponding {@link UploadItem}.
- *
- * As a special case, "/metadata" at the end of the path prefix is discarded.
- * This allows the metadata JSON written by export to be read back in during
- * uploads. See: [Note: Fold "metadata" directory into parent folder].
- */
+// This disambiguates sibling metadata; it is not necessarily a readable path.
export type UploadPathPrefix = string;
-/**
- * Return the {@link UploadPathPrefix} for the given {@link pathOrName} of an
- * item being uploaded.
- */
export const uploadPathPrefix = (pathOrName: string) => {
const folderPath = dirname(pathOrName);
if (basename(folderPath) == exportMetadataDirectoryName) {
@@ -189,13 +46,6 @@ export const uploadPathPrefix = (pathOrName: string) => {
export type UploadItemAndPath = [UploadItem, string];
-/**
- * Build a lookup of album-level Takeout `metadata.json` files by their
- * containing folder path.
- *
- * This only indexes files named exactly `metadata.json`. If multiple entries
- * exist for the same folder, the first one in the upload list is retained.
- */
const takeoutAlbumMetadataJSONItemsByFolderPath = (
uploadItemAndPaths: UploadItemAndPath[],
) => {
@@ -209,14 +59,6 @@ const takeoutAlbumMetadataJSONItemsByFolderPath = (
return result;
};
-/**
- * Return the album-level Takeout `metadata.json` upload item for the given
- * folder path, if one was included in the upload list.
- *
- * The `folderPath` must match the metadata file's containing folder exactly.
- * The returned item is not parsed here; callers parse its `title` when they
- * need an album-name suggestion.
- */
export const takeoutAlbumMetadataJSONItemForFolder = (
uploadItemAndPaths: UploadItemAndPath[],
folderPath: string,
@@ -226,33 +68,6 @@ export const takeoutAlbumMetadataJSONItemForFolder = (
);
};
-/**
- * Group files that are that have the same parent folder into collections.
- *
- * This is used to segregate the list of {@link UploadItemAndPath}s that we
- * obtain when an upload is initiated into per-collection groups when the user
- * chooses the "parent" {@link CollectionMapping} option.
- *
- * For example, if the user selects files have a directory structure like:
- *
- * a
- * / | \
- * b j c
- * /|\ / \
- * e f g h i
- *
- * The files will grouped into 3 collections:
- *
- * [
- * a => [j],
- * b => [e, f, g],
- * c => [h, i]
- * ]
- *
- * @param defaultFolderName Optional collection name to use for any rooted files
- * that do not have a parent folder. The function will throw if a default is not
- * provided and we encounter any such files without a parent.
- */
export const groupItemsBasedOnParentFolder = async (
uploadItemAndPaths: UploadItemAndPath[],
defaultFolderName: string | undefined,
@@ -264,19 +79,7 @@ export const groupItemsBasedOnParentFolder = async (
for (const [uploadItem, pathOrName] of uploadItemAndPaths) {
let folderPath = dirname(pathOrName);
let folderName = basename(folderPath);
- // [Note: Fold "metadata" directory into parent folder]
- //
- // If the parent folder of a file is "metadata" (the directory in which
- // the exported JSON files are written), then we consider it to be part
- // of the parent folder.
- //
- // e.g. for the file list
- //
- // [a/x.png, a/metadata/x.png.json]
- //
- // we want both to be grouped into the collection "a". This is so that
- // we can cluster the metadata JSON files in the same collection as the
- // file it is for.
+ // Exported metadata/ files belong to their parent album.
if (folderName == exportMetadataDirectoryName) {
folderPath = dirname(folderPath);
folderName = basename(folderPath);
@@ -309,11 +112,6 @@ export interface LivePhotoAssets {
video: UploadItem;
}
-/**
- * An upload item with both parts of a live photo clubbed together.
- *
- * See: [Note: Intermediate file types during upload].
- */
export interface ClusteredUploadItem {
localID: number;
collectionID: number;
@@ -326,41 +124,12 @@ export interface ClusteredUploadItem {
livePhotoAssets?: LivePhotoAssets;
}
-/**
- * The file that we hand off to the uploader. Essentially
- * {@link ClusteredUploadItem} with the {@link collection} attached to it.
- *
- * See: [Note: Intermediate file types during upload].
- */
export type UploadableUploadItem = ClusteredUploadItem & {
collection: Collection;
};
-/**
- * Result of {@link markUploadedAndObtainProcessableItem}; see the documentation
- * of that function for the meaning and cases of this type.
- */
export type ProcessableUploadItem = File | TimestampedFileSystemUploadItem;
-/**
- * As the long name suggests, this function does a rather specific thing:
- *
- * - If we're running in the context of the web app, it will return the
- * {@link File} object that best represents the newly uploaded item. For
- * images and videos, this'll be the newly uploaded file itself. For live
- * photos, this will be the {@link File} object for the image component of the
- * live photo.
- *
- * - If we're running in the context of the desktop app, it will first mark the
- * item as having been uploaded in the persistent pending upload list that the
- * desktop app keeps (so that they can be resumed on restarts). After this,
- * it'll try to convert the item to a {@link TimestampedFileSystemUploadItem}
- * if possible, otherwise will return the web {@link File}. As with the web
- * case, in case of live photos the image component will be used in these
- * transformations.
- *
- * @param item An {@link ClusteredUploadItem} that was recently uploaded.
- */
export const markUploadedAndObtainProcessableItem = async (
item: ClusteredUploadItem,
): Promise<ProcessableUploadItem> => {
@@ -421,28 +190,6 @@ export const markUploadedAndObtainProcessableItem = async (
}
};
-/**
- * Convert an {@link TimestampedFileSystemUploadItem} item back into a
- * {@link FileSystemUploadItem} if the underlying file hasn't changed.
- *
- * While this functionality is not directly related to upload, this function is
- * kept here since it is in some sense the inverse of
- * {@link markUploadedAndObtainProcessableItem}.
- *
- * @param item A {@link TimestampedFileSystemUploadItem}.
- *
- * @param fsStatMtime A function that can be used to perform IPC and obtain the
- * last modified time from the node side.
- *
- * @returns If the last modified time of the file system file pointed to by the
- * given {@link item} is the same as what is recorded within the structure, then
- * return the wrapped {@link FileSystemUploadItem}, otherwise return
- * `undefined`.
- *
- * In case of any errors, also return `undefined`. This is because errors are
- * expected if the underlying file system file was, e.g. renamed or removed
- * between the time the file was uploaded and we got around to processing it.
- */
export const fileSystemUploadItemIfUnchanged = async (
{ fsUploadItem, lastModifiedMs }: TimestampedFileSystemUploadItem,
fsStatMtime: (path: string) => Promise<number>,
@@ -451,8 +198,7 @@ export const fileSystemUploadItemIfUnchanged = async (
if (typeof fsUploadItem == "string") {
path = fsUploadItem;
} else if (Array.isArray(fsUploadItem)) {
- // The last modified time we recorded was of the zip file that contains
- // the entry.
+ // The recorded timestamp belongs to the containing ZIP.
path = fsUploadItem[0];
} else {
path = fsUploadItem.path;
@@ -473,11 +219,6 @@ export const fileSystemUploadItemIfUnchanged = async (
}
};
-/**
- * For each of cases of {@link UploadItem} that apply when we're running in the
- * context of our desktop app, return a value that can be passed to
- * {@link Electron} functions over IPC.
- */
export const toPathOrZipEntry = (fsUploadItem: FileSystemUploadItem) =>
typeof fsUploadItem == "string" || Array.isArray(fsUploadItem)
? fsUploadItem
@@ -503,40 +244,9 @@ export type UploadResult =
| { type: "uploadedWithStaticThumbnail"; file: EnteFile }
| { type: "uploaded"; file: EnteFile };
-/**
- * Return true to disable the upload of files via Cloudflare Workers.
- *
- * [Note: Faster uploads via workers]
- *
- * These workers were introduced as a way of make file uploads faster:
- * https://ente.com/blog/tech/making-uploads-faster/
- *
- * By default, that's the route we take. However, there are multiple reasons why
- * this might be disabled.
- *
- * 1. During development and when self-hosting it we disable them to directly
- * upload to the S3-compatible URLs returned by the ente API.
- *
- * 2. In rare cases, the user might have trouble reaching Cloudflare's network
- * from their ISP. In such cases, the user can locally turn this off via
- * settings.
- *
- * 3. There is also the original global toggle that was added when this feature
- * was introduced.
- *
- * This function returns the in-memory value. It is updated when #2 changes (if
- * we're running in a context where that makes sense). The #3 remote status is
- * obtained once, on app start.
- */
export const shouldDisableCFUploadProxy = () =>
_state.shouldDisableCFUploadProxy;
-/**
- * Update the in-memory value of {@link shouldDisableCFUploadProxy}.
- *
- * @param savedPreference An optional user preference that the user has
- * expressed to disable the proxy.
- */
export const updateShouldDisableCFUploadProxy = async (
savedPreference?: boolean,
) => {
@@ -544,25 +254,14 @@ export const updateShouldDisableCFUploadProxy = async (
savedPreference || (await computeShouldDisableCFUploadProxy());
};
-/**
- * Return `true` if uploads should include checksum metadata.
- */
export const areChecksumProtectedUploadsEnabled = () =>
_state.checksumProtectedUploadsEnabled;
-/**
- * Update the in-memory value controlling checksum protected uploads.
- */
export const updateChecksumProtectedUploadsEnabled = (enabled: boolean) => {
_state.checksumProtectedUploadsEnabled = enabled;
};
const computeShouldDisableCFUploadProxy = async () => {
- // If a custom origin is set, that means we're not running a production
- // deployment (maybe we're running locally, or being self-hosted).
- //
- // In such cases, disable the Cloudflare upload proxy (which won't work for
- // self-hosters), and instead just directly use the upload URLs that museum
- // gives us.
+ // The worker proxy is configured only for Ente's hosted API.
return !!(await customAPIOrigin());
};
diff --git a/web/packages/gallery/services/upload/remote.ts b/web/packages/gallery/services/upload/remote.ts
index 204fad7cae..63f7a32250 100644
--- a/web/packages/gallery/services/upload/remote.ts
+++ b/web/packages/gallery/services/upload/remote.ts
@@ -12,37 +12,12 @@ 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>;
const ObjectUploadURLResponse = z.object({ urls: ObjectUploadURL.array() });
-/**
- * Fetch a fresh list of URLs from remote that can be used to upload objects.
- *
- * @param countHint An approximate number of objects that we're expecting to
- * upload.
- *
- * @returns A list of pre-signed object URLs that can be used to upload data to
- * the S3 bucket. Each URL also has an associated "object key" with which remote
- * will refer to the uploaded object after it has been uploaded.
- */
export const fetchUploadURLs = async (countHint: number) => {
const count = Math.min(50, countHint * 2);
const res = await fetch(
@@ -74,9 +49,6 @@ export const fetchUploadURLWithMetadata = async ({
return ObjectUploadURL.parse(await res.json());
};
-/**
- * Sibling of {@link fetchUploadURLWithMetadata} for public albums.
- */
export const fetchPublicAlbumsUploadURLWithMetadata = async (
{
contentLength,
@@ -123,9 +95,6 @@ export const fetchMultipartUploadURLsWithMetadata = async ({
return MultipartUploadURLs.parse(await res.json());
};
-/**
- * Sibling of {@link fetchMultipartUploadURLsWithMetadata} for public albums.
- */
export const fetchPublicAlbumsMultipartUploadURLsWithMetadata = async (
{
contentLength,
@@ -152,29 +121,9 @@ 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(),
});
@@ -182,18 +131,6 @@ export type MultipartUploadURLs = z.infer<typeof MultipartUploadURLs>;
const MultipartUploadURLsResponse = z.object({ urls: MultipartUploadURLs });
-/**
- * Fetch a {@link MultipartUploadURLs} structure from remote that can be used to
- * upload a large object by splitting it into {@link uploadPartCount} parts.
- *
- * See: [Note: Multipart uploads].
- *
- * @param uploadPartCount The number of parts in which we want to upload the
- * object.
- *
- * @returns A structure ({@link MultipartUploadURLs}) containing pre-signed URLs
- * for uploading each part, a completion URL, and the final object key.
- */
export const fetchMultipartUploadURLs = async (uploadPartCount: number) => {
const count = uploadPartCount;
const res = await fetch(
@@ -204,16 +141,6 @@ export const fetchMultipartUploadURLs = async (uploadPartCount: number) => {
return MultipartUploadURLsResponse.parse(await res.json()).urls;
};
-/**
- * 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;
}
@@ -241,9 +168,6 @@ export const putFile = async (
}),
);
-/**
- * Variant of {@link putFile} that uses a CF worker.
- */
export const putFileViaWorker = async (
fileUploadURL: string,
fileData: Uint8Array<ArrayBuffer>,
@@ -264,24 +188,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>,
@@ -303,9 +209,6 @@ export const putFilePart = async (
return nullToUndefined(res.headers.get("etag"));
};
-/**
- * Variant of {@link putFilePart} that uses a CF worker.
- */
export const putFilePartViaWorker = async (
partUploadURL: string,
partData: Uint8Array<ArrayBuffer>,
@@ -329,84 +232,15 @@ 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.
- */
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; interpolate them verbatim.
const resultParts = parts.map(
(part) =>
`<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.eTag}</ETag></Part>`,
@@ -414,63 +248,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 multiple pre-signed URLs from remote (museum). The specific API
- * call will be different (because of the different authentication
- * mechanisms) when we're running in the context of the photos app
- * ({@link fetchMultipartUploadURLs}) and when we're running in the context
- * of the public albums app
- * ({@link fetchPublicAlbumsMultipartUploadURLsWithMetadata}).
- *
- * 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[],
@@ -484,9 +261,6 @@ export const completeMultipartUpload = (
}),
);
-/**
- * Variant of {@link completeMultipartUpload} that uses a CF worker.
- */
export const completeMultipartUploadViaWorker = async (
completionURL: string,
completedParts: MultipartCompletedPart[],
@@ -514,66 +288,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 {@link EnteFile} on remote by providing remote with information
- * about the file's contents (objects) that were uploaded, and other metadata
- * about the file.
- *
- * Remote only, does not modify local state.
- *
- * @returns the newly created {@link EnteFile}.
- */
export const postEnteFile = async (
postFileRequest: PostEnteFileRequest,
): Promise<RemoteEnteFile> => {
@@ -586,9 +306,6 @@ export const postEnteFile = async (
return RemoteEnteFile.parse(await res.json());
};
-/**
- * Sibling of {@link postEnteFile} for public albums.
- */
export const postPublicAlbumsEnteFile = async (
postFileRequest: PostEnteFileRequest,
diff --git a/web/packages/gallery/services/upload/upload-service.ts b/web/packages/gallery/services/upload/upload-service.ts
index a1ba072f73..8cc95c0882 100644
--- a/web/packages/gallery/services/upload/upload-service.ts
+++ b/web/packages/gallery/services/upload/upload-service.ts
@@ -80,54 +80,17 @@ import {
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!
- */
+ // Streams are single-use and always emit encryption-sized chunks.
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 uploadURLs: ObjectUploadURL[] = [];
private pendingUploadCount = 0;
@@ -154,7 +117,7 @@ class UploadService {
this.uploadURLs = [];
return;
}
- await this.refillUploadURLs(); /* prefetch */
+ await this.refillUploadURLs();
}
reducePendingUploadCount() {
@@ -206,10 +169,6 @@ class UploadService {
this.activeUploadURLRefill = undefined;
}
- // Ensure that the upload URLs we have are unique.
- //
- // Sanity check added when this was a new implementation. Have kept it
- // around, but it can be removed too.
if (
this.uploadURLs.length !=
new Set(this.uploadURLs.map((u) => u.url)).size
@@ -276,14 +235,10 @@ 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) => {
if (uploadItem instanceof File) return uploadItem.name;
if (typeof uploadItem == "string") return basename(uploadItem);
@@ -291,59 +246,21 @@ export const uploadItemFileName = (uploadItem: UploadItem) => {
return uploadItem.file.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;
}
@@ -354,43 +271,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;
@@ -398,15 +291,12 @@ interface EncryptedFilePieces {
export interface PotentialLivePhotoAsset {
fileName: string;
- fileType: number /* FileType | -1 */;
+ 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,
@@ -423,11 +313,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 can name the image half IMG_0001.mp4.jpg.
gExt ? `.${gExt}` : undefined,
);
gPrunedName = removePotentialLivePhotoSuffix(gName);
@@ -443,12 +329,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 */
+ // The live-photo ZIP encoder cannot stream, so bound each component.
+ const maxAssetSize = 20 * 1024 * 1024;
const fSize = await uploadItemSize(f.uploadItem);
const gSize = await uploadItemSize(g.uploadItem);
if (fSize > maxAssetSize || gSize > maxAssetSize) {
@@ -458,11 +340,6 @@ 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).
-
const fParsedMetadataJSON = matchJSONMetadata(
f.pathPrefix,
f.collectionID,
@@ -487,24 +364,13 @@ 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 */
+ // One component can lack timezone data, producing up to a one-day skew.
+ 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.
+ // Google Takeout omits JSON for the video half of a live photo.
if (
(!fParsedMetadataJSON && !gParsedMetadataJSON) ||
(fParsedMetadataJSON && gParsedMetadataJSON)
@@ -513,17 +379,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 this to live-photo filenames.
const suffix_hvec = "_HVEC";
let foundSuffix: string | undefined;
@@ -543,9 +405,6 @@ 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 = async (uploadItem: UploadItem): Promise<number> => {
if (uploadItem instanceof File) return uploadItem.size;
if (typeof uploadItem == "string")
@@ -555,26 +414,9 @@ const uploadItemSize = async (uploadItem: UploadItem): Promise<number> => {
return uploadItem.file.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.
- */
const uploadItemCreationDate = async (
uploadItem: UploadItem,
- fileType: number /* FileType */,
+ fileType: number,
parsedMetadataJSON: ParsedMetadataJSON | undefined,
) => {
if (parsedMetadataJSON?.creationTime)
@@ -594,144 +436,30 @@ 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 true, duplicate files already owned by the user are reused without
- * being added to the current upload collection.
- * This is used when the current collection is only an upload staging target.
- */
skipDuplicateAddToUploadCollection?: boolean;
- /**
- * If true, media originating from Google Photos partner sharing is
- * uploaded. Otherwise it is skipped before reading the media file.
- */
includePartnerSharedFiles?: 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;
- /**
- * 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,
@@ -761,22 +489,6 @@ export const upload = async (
}
}
- /*
- * 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.
- *
- * When we're in the context of our desktop app and have a path, it
- * might be possible 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 {
@@ -793,7 +505,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();
@@ -822,16 +534,12 @@ export const upload = async (
}
if (skipDuplicateAddToUploadCollection) {
- // The real target collection is updated after the upload batch.
- // Report duplicate reuse as a success without creating a staging
- // collection symlink.
return {
type: "addedSymlink",
file: matchInSameCollection ?? anyMatch,
};
}
- // Any of the matching files can be used to add a symlink.
const symlink = Object.assign({}, anyMatch);
symlink.collectionID = collection.id;
await addToCollection(collection, [symlink]);
@@ -893,19 +601,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:
@@ -916,16 +621,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).
- *
- * Can be used with the following functions:
- *
- * - {@link fetchUploadURLs}
- * - {@link fetchMultipartUploadURLs}
- *
- */
const translateURLFetchErrorIfNeeded = (e: unknown) => {
if (e instanceof HTTPError) {
switch (e.res.status) {
@@ -940,76 +635,6 @@ const translateURLFetchErrorIfNeeded = (e: unknown) => {
return e;
};
-/**
- * Read the given file or path or zip item into an in-memory representation.
- *
- * [Note: Reading a UploadItem]
- *
- * The file can be either a web
- * [File](https://developer.mozilla.org/en-US/docs/Web/API/File), the absolute
- * path to a file on desk, a combination of these two, or a entry in a zip file
- * on the user's local file system.
- *
- * tl;dr; There are four cases:
- *
- * 1. web / File
- * 2. desktop / File (+ path)
- * 3. desktop / path
- * 4. desktop / ZipItem
- *
- * For the when and why, read on.
- *
- * The code that accesses files (e.g. uplaads) gets invoked in two contexts:
- *
- * 1. web: the normal mode, when we're running in as a web app in the browser.
- *
- * 2. desktop: when we're running inside our desktop app.
- *
- * In the web context, we'll always get a File, since within the browser we
- * cannot programmatically construct paths to or arbitrarily access files on the
- * user's file system.
- *
- * > Note that even if we were to somehow have an absolute path at hand, we
- * cannot programmatically create such File objects to arbitrary absolute
- * paths on user's local file system for security reasons.
- *
- * So in the web context, this will always be a File we get as a result of an
- * explicit user interaction (e.g. drag and drop or using a file selector).
- *
- * In the desktop context, this can be either a File (+ path), or a path, or an
- * entry within a zip file.
- *
- * 2. If the user provided us this file via some user interaction (say a drag
- * and a drop), this'll still be a File. But unlike in the web context, we
- * also have access to the full path of this file.
- *
- * 3. In addition, when running in the desktop app we have the ability to
- * initiate programmatic access absolute paths on the user's file system. For
- * example, if the user asks us to watch certain folders on their disk for
- * changes, we'll be able to pick up new images being added, and in such
- * cases, the parameter here will be a path. Another example is when resuming
- * an previously interrupted upload - we'll only have the path at hand in
- * such cases, not the original File object since the app subsequently
- * restarted.
- *
- * 4. The user might've also initiated an upload of a zip file (or we might be
- * resuming one). In such cases we will get a tuple (path to the zip file on
- * the local file system, and the name of the entry within that zip file).
- *
- * Case 3 and 4, when we're provided a path, are simple. We don't have a choice,
- * since we cannot still programmatically construct a File object (we can
- * construct it on the Node.js layer, but it can't then be transferred over the
- * IPC boundary). So all our operations use the path itself.
- *
- * Case 2 involves a choice on a use-case basis. Neither File nor the path is a
- * better choice for all use cases.
- *
- * > The advantage of the File object is that the browser has already read it
- * into memory for us. The disadvantage comes in the case where we need to
- * communicate with the native Node.js layer of our desktop app. Since this
- * communication happens over IPC, the File's contents need to be serialized
- * and copied, which is a bummer for large videos etc.
- */
const readUploadItem = async (uploadItem: UploadItem): Promise<FileStream> => {
let underlyingStream: ReadableStream;
let file: File | undefined;
@@ -1039,9 +664,6 @@ const readUploadItem = async (uploadItem: UploadItem): Promise<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).
let pending: Uint8Array | undefined;
const transformer = new TransformStream<Uint8Array, Uint8Array>({
transform(
@@ -1079,10 +701,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,
@@ -1101,8 +719,6 @@ 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.
extension: img.fileTypeInfo.extension,
},
fileSize: img.fileSize + vid.fileSize,
@@ -1110,16 +726,6 @@ const readLivePhotoDetails = async ({ image, video }: LivePhotoAssets) => {
};
};
-/**
- * Read the beginning of the given file (or its path), or use its filename as a
- * fallback, 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 } =
await readUploadItem(uploadItem);
@@ -1135,14 +741,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>> =>
@@ -1153,10 +751,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,
@@ -1255,18 +849,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,
@@ -1294,21 +882,12 @@ 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 produced non-numeric dimensions in real uploads.
const metadata: FileMetadata = {
fileType,
title: fileName,
@@ -1359,9 +938,6 @@ const tryExtractImageMetadata = async (
): Promise<ParsedMetadata | undefined> => {
let file: File;
if (typeof uploadItem == "string" || Array.isArray(uploadItem)) {
- // The library we use for extracting Exif from images, ExifReader,
- // doesn't support streams. But unlike videos, for images it is
- // reasonable to read the entire stream into memory here.
const { response } = await readStream(ensureElectron(), uploadItem);
const path = typeof uploadItem == "string" ? uploadItem : uploadItem[1];
const opts = lastModifiedMs ? { lastModified: lastModifiedMs } : {};
@@ -1401,19 +977,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 } = await readUploadItem(uploadItem);
const hashState = await worker.chunkHashInit();
@@ -1430,23 +993,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;
@@ -1472,20 +1025,12 @@ 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 },
await readUploadItem(livePhotoAssets.image),
);
const videoFileStreamOrData = await 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).
+ // The ZIP encoder accepts blobs or bytes, not streams. The size was bounded above.
const fileOrData = async (sd: FileStream | Uint8Array<ArrayBuffer>) => {
const fos = async ({ file, stream }: FileStream) =>
file ? file : await readEntireStream(stream);
@@ -1512,18 +1057,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,
@@ -1535,7 +1068,6 @@ const augmentWithThumbnail = async (
const electron = globalThis.electron;
- // 1. Native thumbnail generation using items's (effective) path.
if (electron && !(uploadItem instanceof File)) {
try {
thumbnail = await generateThumbnailNative(
@@ -1551,29 +1083,13 @@ const augmentWithThumbnail = async (
if (!thumbnail) {
let blob: Blob | undefined;
if (uploadItem instanceof File) {
- // 2. Browser based thumbnail generation for File (blobs).
blob = uploadItem;
} else {
- // 3. Browser based thumbnail generation for paths.
- //
- // We can only get here when we're running in our desktop app (since
- // only that works with non-File uploadItems), and the thumbnail
- // generation failed.
- //
- // There are no expected scenarios when this should happen.
- //
- // The fallback in this case involves reading the entire stream into
- // memory, and passing that data across the IPC boundary in a single
- // go (i.e. not in a streaming manner). This is risky for videos of
- // unbounded sizes, and since anyways we are not expected to come
- // here for videos, so we only apply this fallback for images.
-
+ // Never buffer an unbounded video after native thumbnailing fails.
if (fileTypeInfo.fileType == FileType.image) {
const data = await readEntireStream(fileStream.stream);
blob = new Blob([data]);
- // The Readable stream cannot be read twice, so use the data
- // directly for subsequent steps.
fileData = data;
} else {
const fileName = uploadItemFileName(uploadItem);
@@ -1716,10 +1232,7 @@ 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.
+ // readUploadItem promised exactly chunkCount chunks.
controller.close();
throw new Error("Unexpected stream state");
}
@@ -1793,12 +1306,6 @@ 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.
const maxPercent = Math.floor(95 + 5 * Math.random());
let fileObjectKey: string;
@@ -1809,8 +1316,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,
@@ -1893,22 +1398,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) =>
@@ -2008,7 +1497,7 @@ const uploadStreamUsingMultipart = async (
updateUploadProgress(fileLocalID, percentPerPart * partNumber);
completedParts.push({ partNumber, eTag });
- parts[index] = new Uint8Array(0); // release memory
+ parts[index] = new Uint8Array(0);
}
const completionURL = multipartUploadURLs.completeURL;
@@ -2078,11 +1567,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>,
) => {
@@ -2095,9 +1579,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/packages/gallery/services/video.ts b/web/packages/gallery/services/video.ts
index 6a5df9ccf8..f60a187df5 100644
--- a/web/packages/gallery/services/video.ts
+++ b/web/packages/gallery/services/video.ts
@@ -48,110 +48,33 @@ export type HLSGenerationStatus =
| { enabled: true; status?: HLSGenerationEnabledStatus };
interface VideoProcessingQueueItem {
- /**
- * The {@link EnteFile} (guaranteed to be of {@link FileType.video}) whose
- * video data needs processing.
- */
file: EnteFile;
- /**
- * The {@link TimestampedFileSystemUploadItem} when available for the newly
- * uploaded {@link file}.
- *
- * It will be present when this queue item was enqueued during a upload from
- * the current client. If present, this serves as an optimization allowing
- * us to directly read the file off the user's file system.
- */
timestampedUploadItem?: TimestampedFileSystemUploadItem;
}
-const idleWaitInitial = 10 * 1000; /* 10 sec */
-const idleWaitMax = idleWaitInitial * 2 ** 6; /* 640 sec */
+const idleWaitInitial = 10 * 1000;
+const idleWaitMax = idleWaitInitial * 2 ** 6;
-/**
- * Internal in-memory state shared by the functions in this module.
- *
- * This entire object will be reset on logout.
- */
class VideoState {
- /**
- * `true` if the generation of HLS streams has been enabled on this client.
- */
isHLSGenerationEnabled = false;
- /**
- * Subscriptions to {@link HLSGenerationStatus} updates attached using
- * {@link hlsGenerationStatusSubscribe}.
- */
hlsGenerationStatusListeners: (() => void)[] = [];
- /**
- * Snapshot of the {@link HLSGenerationStatus} returned by the
- * {@link hlsGenerationStatusSnapshot} function.
- */
hlsGenerationStatusSnapshot: HLSGenerationStatus | undefined;
- /**
- * Value of the {@link status} field in the last
- * {@link hlsGenerationStatusSnapshot}.
- */
lastEnabledStatus: HLSGenerationEnabledStatus | undefined;
- /**
- * Queue of recently uploaded items waiting to be processed.
- */
liveQueue: VideoProcessingQueueItem[] = [];
- /**
- * Active queue processor, if any.
- */
queueProcessor: Promise<void> | undefined;
- /**
- * A promise that the main processing loop waits for in addition to the idle
- * timeout. Can be resolved using {@link resolveTick}.
- */
tick: Promise<void> | undefined;
- /**
- * A function that can be called to resolve {@link tick}.
- *
- * See: [Note: Exiting idle wait of processing loop].
- */
resolveTick: (() => void) | undefined;
- /**
- * The time to sleep if nothing is pending.
- *
- * Goes from {@link idleWaitInitial} to {@link idleWaitMax} in doublings.
- * Reset back to {@link idleWaitInitial} in case of any activity.
- */
idleWait = idleWaitInitial;
- /**
- * `true` if we have synced at least once with remote.
- *
- * We use this to gate the processing of the backfill queue to avoid
- * unnecessarily picking up files that have already been indexed elsewhere
- * (we'll still check before processing them, but still that's unnecessary
- * work this flag can save us).
- */
haveSyncedOnce = false;
}
-/**
- * State shared by the functions in this module. See {@link VideoState}.
- */
let _state = new VideoState();
-/**
- * Reset any internal state maintained by the module.
- *
- * This is primarily meant as a way for stateful apps (e.g. photos) to clear any
- * user specific state on logout.
- */
export const resetVideoState = () => {
- // Note: We rely on [Note: Full reload on logout] to abort any in-flight
- // requests.
+ // Logout performs a full reload, which aborts any in-flight native work.
_state = new VideoState();
};
-/**
- * A function that can be used to subscribe to updates in the HLS generation
- * settings and status.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
export const hlsGenerationStatusSubscribe = (
onChange: () => void,
): (() => void) => {
@@ -162,18 +85,6 @@ export const hlsGenerationStatusSubscribe = (
};
};
-/**
- * Return the last know, cached {@link HLSGenerationStatus}.
- *
- * See also {@link hlsGenerationStatusSubscribe}.
- *
- * This function can be safely called even if {@link isHLSGenerationSupported}
- * is `false` (in such cases, it will always return `undefined`). This is so
- * that it can be unconditionally called as part of a React hook.
- *
- * A return value of `undefined` indicates that the HLS generation subsystem has
- * not been initialized yet.
- */
export const hlsGenerationStatusSnapshot = () =>
_state.hlsGenerationStatusSnapshot;
@@ -182,11 +93,6 @@ const setHLSGenerationStatusSnapshot = (snapshot: HLSGenerationStatus) => {
_state.hlsGenerationStatusListeners.forEach((l) => l());
};
-/**
- * A variant of {@link setHLSGenerationStatusSnapshot} that only triggers an
- * update of the snapshot if the enabled state is different from the last known
- * enabled state.
- */
const updateSnapshotIfNeeded = (
status: HLSGenerationEnabledStatus | undefined,
) => {
@@ -197,47 +103,21 @@ const updateSnapshotIfNeeded = (
}
};
-/**
- * Return `true` if this client is capable of generating HLS streams for
- * uploaded videos.
- */
export const isHLSGenerationSupported = isDesktop;
-/**
- * Initialize the video processing subsystem unless the user has disabled HLS
- * generation in settings.
- */
export const initVideoProcessing = async () => {
let enabled = false;
if (await savedGenerateHLS()) enabled = true;
_state.isHLSGenerationEnabled = enabled;
- // Update snapshot to reflect the enabled setting. The status will get
- // filled in when we tick.
setHLSGenerationStatusSnapshot({ enabled });
};
-/**
- * Return the persisted user preference for HLS generation.
- */
const savedGenerateHLS = async () => await getKVB("generateHLS");
-/**
- * Update the persisted user preference for HLS generation.
- *
- * Use {@link savedGenerateHLS} to get the persisted value back.
- */
const saveGenerateHLS = (enabled: boolean) => setKV("generateHLS", enabled);
-/**
- * Enable or disable (toggle) the HLS generation on this client.
- *
- * When HLS generation is enabled, this client will process videos to generate a
- * streamable variant of them.
- *
- * Precondition: {@link isHLSGenerationSupported} must be `true`.
- */
export const toggleHLSGeneration = async () => {
if (!isHLSGenerationSupported) {
assertionFailed();
@@ -246,88 +126,25 @@ export const toggleHLSGeneration = async () => {
const enabled = !_state.isHLSGenerationEnabled;
- // Clear transient fields.
_state.lastEnabledStatus = undefined;
- // Update disk.
await saveGenerateHLS(enabled);
- // Update in memory.
_state.isHLSGenerationEnabled = enabled;
- // Update snapshot. Right now we only set the enabled setting. The status
- // will get filled in when we tick.
setHLSGenerationStatusSnapshot({ enabled });
- // Wake up the processor if needed.
if (enabled) tickNow();
};
export interface HLSPlaylistData {
- /** A data URL to a HLS playlist that streams the video. */
playlistURL: string;
- /** The width of the video (px). */
width: number;
- /** The height of the video (px). */
height: number;
}
-/**
- * See: [Note: Caching HLS playlist data] for the semantics of "skip".
- */
+// "skip" is stable ineligibility; undefined may become a playlist later.
export type HLSPlaylistDataForFile = HLSPlaylistData | "skip" | undefined;
-/**
- * Return a HLS playlist that can be used to stream playback of then given video
- * {@link file}.
- *
- * @param file An {@link EnteFile} of type video.
- *
- * @param publicAlbumsCredentials Credentials to use for fetching the HLS
- * playlist when we are running in the context of the public albums app. If
- * these are not specified, then the credentials of the logged in user are used.
- *
- * @returns The HLS playlist as a string (along with the dimensions of the video
- * it will play), or `undefined` if there is no video preview associated with
- * the given file.
- *
- * See: [Note: Video playlist and preview]
- *
- * ---
- *
- * [Note: Caching HLS playlist data]
- *
- * The playlist data can be cached in an asymmetric manner.
- *
- * - If a file has a corresponding HLS playlist, then currently there is no
- * scenario (apart from file deletion, where the playlist also gets deleted)
- * where the playlist is deleted after being created. There is a limit to the
- * validity of the pre-signed chunk URLs within the playlist we create (which
- * we do handle, see `createHLSPlaylistItemDataValidity`), but the original
- * playlist itself does not change. Updates are technically possible, but
- * apart from a misbehaving client, are not expected (and should be no-ops in
- * the rare cases they happen, since effectively same playlist should get
- * regenerated again). All in all, this means that a positive result ("this
- * file has a playlist") can be cached indefinitely.
- *
- * - If a file does not have a HLS playlist, it might be because it is not
- * eligible for being streamed (e.g. it is already small and in a compatible
- * codec). See [Note: Marking files which do not need video processing] for
- * more details of this case. In particular, we can cache this state in memory
- * indefinitely too, since there isn't a current case where either this
- * eligibility can change, or the client gain the ability to handle them
- * without restarting.
- *
- * - Finally, if a file does not have an HLS playlist but and it is eligible for
- * being streamed, then a client (this one, or a different one) can process it
- * at any arbitrary time. So the negative result ("this file does not have a
- * playlist") cannot be cached.
- *
- * So while we can easily cache the first case ("this file has a playlist") and
- * second case ("this file doesn't need a streaming variant"), we need to deal
- * with the third case ("this file does not have a playlist") by marking the
- * cached values as "transient" and always recheck for a playlist when opening
- * the slide.
- */
export const hlsPlaylistDataForFile = async (
file: EnteFile,
publicAlbumsCredentials?: PublicAlbumsCredentials,
@@ -354,7 +171,6 @@ export const hlsPlaylistDataForFile = async (
height,
} = await decryptPlaylistJSON(playlistFileData, file);
- // A playlist format the current client does not understand.
if (type != "hls_video") return undefined;
const videoURL = await fetchFilePreviewData(
@@ -365,78 +181,13 @@ export const hlsPlaylistDataForFile = async (
);
if (!videoURL) return undefined;
- // [Note: HLS playlist format]
- //
- // The decrypted playlist is a regular HLS playlist for an encrypted media
- // stream, except that it uses a placeholder "output.ts" which needs to be
- // replaced with the URL of the actual encrypted video data. A single URL
- // pointing to the entire encrypted video data suffices; the individual
- // chunks are fetched by HTTP range requests.
- //
- // Here is an example of what the contents of the `playlist` variable might
- // look like at this point:
- //
- // #EXTM3U
- // #EXT-X-VERSION:4
- // #EXT-X-TARGETDURATION:8
- // #EXT-X-MEDIA-SEQUENCE:0
- // #EXT-X-KEY:METHOD=AES-128,URI="data:text/plain;base64,XjvG7qeRrsOpPUbJPh2Ikg==",IV=0x00000000000000000000000000000000
- // #EXTINF:8.333333,
- // #EXT-X-BYTERANGE:3046928@0
- // output.ts
- // #EXTINF:8.333333,
- // #EXT-X-BYTERANGE:3012704@3046928
- // output.ts
- // #EXTINF:2.200000,
- // #EXT-X-BYTERANGE:834736@6059632
- // output.ts
- // #EXT-X-ENDLIST
- //
- // The HLS playlist format is specified in RFC 8216:
- // https://datatracker.ietf.org/doc/html/rfc8216
- //
- // Some notes pertinent to us:
- //
- // - A URI line identifies a media segment.
- //
- // - The EXTINF tag specifies the duration of the media segment (applies
- // only to the next URI line that follows it in the playlist).
- //
- // - The EXT-X-BYTERANGE tag indicates that a media segment is a sub-range
- // of the resource identified by its URI (applies only to the next URI
- // line that follows it in the playlist). The value should be of the
- // format `<n>[@<o>]` where n is an integer indicating the length of the
- // sub-range in bytes, and if present, o is the integer indicating the
- // start of the sub-range as a byte offset from the beginning of the
- // resource. If o is not present, the sub-range begins at the next byte
- // following the sub-range of the previous media segment.
- //
- // - Media segments may be encrypted, and the EXT-X-KEY tag specifies how to
- // decrypt them. It applies to all subsequent media segment (until another
- // EXT-X-KEY). Value is an `<attribute-list>`, consisting of the METHOD
- // (AES-128 for us), URI and IV attributes. The URI attribute value is a
- // quoted string containing a URI that specifies how to obtain the key.
-
+ // Native playlists use this placeholder for the signed range-request URL.
const playlist = playlistTemplate.replaceAll(
"\noutput.ts",
`\n${videoURL}`,
);
- // From the RFC
- //
- // > Each playlist file must be identifiable either by the path component of
- // > its URI (ending with either ".m3u8" or ".m3u") or by its HTTP
- // > Content-Type ("application/vnd.apple.mpegurl" or "audio/mpegurl").
- // > Clients should refuse to parse playlists that are not so identified.
- //
- // As of now (2025), there isn't a way to set the filename for a URL created
- // via createObjectURL, so instead we create a "data:" URL where the MIME
- // type can be specified.
- //
- // The generated data URL be of the form:
- //
- // data:application/vnd.apple.mpegurl;base64,<base64-string>
-
+ // HLS clients require a recognizable playlist MIME type or filename.
const playlistURL = await blobToDataURL(
new Blob([playlist], { type: "application/vnd.apple.mpegurl" }),
);
@@ -445,29 +196,10 @@ export const hlsPlaylistDataForFile = async (
};
const PlaylistJSON = z.object({
- /**
- * The type of the playlist.
- *
- * The only value we currently understand on this client is "hls_video", but
- * for future extensibility this might be other values too.
- */
type: z.string(),
- /**
- * The HLS playlist, as a string.
- */
playlist: z.string(),
- /**
- * The width of the video (px).
- */
width: z.number(),
- /**
- * The height of the video (px).
- */
height: z.number(),
- /**
- * The size (in bytes) of the corresponding file containing the video
- * segments that the playlist refers to.
- */
size: z.number(),
});
@@ -482,75 +214,25 @@ const decryptPlaylistJSON = async (
return PlaylistJSON.parse(JSON.parse(jsonString));
};
-/**
- * Convert a blob to a `data:` URL.
- */
const blobToDataURL = (blob: Blob) =>
new Promise<string>((resolve) => {
const reader = new FileReader();
- // We need to cast to a string here. This should be safe since MDN says:
- //
- // > the result attribute contains the data as a data: URL representing
- // > the file's data as a base64 encoded string.
- // >
- // > https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL
reader.onload = () => resolve(reader.result as string);
reader.readAsDataURL(blob);
});
-/**
- * Return the (persistent) {@link Set} containing the ids of the files which
- * have already been processed for generating their streaming variant.
- *
- * {@link savedProcessedVideoFileIDs} and its sibling
- * {@link savedFailedVideoFileIDs} are mutually exclusive - that is, a file ID
- * will be present in only one of them at max. We maintain that invariant in the
- * higher level `mark*` functions when updating either of these persisted sets.
- *
- * The data is retrieved from persistent storage (KV DB), where it is stored as
- * an array.
- */
const savedProcessedVideoFileIDs = () =>
- // See: [Note: Avoiding Zod parsing for large DB arrays]
getKV("videoPreviewProcessedFileIDs").then((v) => new Set(v as number[]));
-/**
- * Return the (persistent) {@link Set} containing the ids of the files for which
- * an attempt to generate a streaming variant failed locally.
- *
- * @see also {@link savedProcessedVideoFileIDs}.
- */
const savedFailedVideoFileIDs = () =>
- // See: [Note: Avoiding Zod parsing for large DB arrays]
getKV("videoPreviewFailedFileIDs").then((v) => new Set(v as number[]));
-/**
- * Update the persisted set of IDs of files which have already been processed
- * and have a video preview generated (either on this client, or elsewhere).
- *
- * @see also {@link savedProcessedVideoFileIDs}.
- */
const saveProcessedVideoFileIDs = (videoFileIDs: Set<number>) =>
setKV("videoPreviewProcessedFileIDs", Array.from(videoFileIDs));
-/**
- * Update the persisted set of IDs of files for which attempt to generate a
- * video preview failed on this client.
- *
- * @see also {@link savedProcessedVideoFileIDs}.
- */
const saveFailedVideoFileIDs = (videoFileIDs: Set<number>) =>
setKV("videoPreviewFailedFileIDs", Array.from(videoFileIDs));
-/**
- * Mark the provided file ID as having been processed to generate a video
- * preview.
- *
- * The mark is persisted locally in IndexedDB (KV DB), so will persist across
- * app restarts (but not across logouts).
- *
- * @see also {@link savedProcessedVideoFileIDs}.
- */
const markProcessedVideoFileID = async (fileID: number) => {
const savedIDs = await savedProcessedVideoFileIDs();
const failedIDs = await savedFailedVideoFileIDs();
@@ -559,10 +241,6 @@ const markProcessedVideoFileID = async (fileID: number) => {
await saveProcessedVideoFileIDs(savedIDs);
};
-/**
- * Mark multiple file IDs as processed. Plural variant of
- * {@link markProcessedVideoFileID}.
- */
const markProcessedVideoFileIDs = async (fileIDs: Set<number>) => {
const savedIDs = await savedProcessedVideoFileIDs();
const failedIDs = await savedFailedVideoFileIDs();
@@ -572,20 +250,6 @@ const markProcessedVideoFileIDs = async (fileIDs: Set<number>) => {
]);
};
-/**
- * Mark the provided file as having failed in a non-transient manner when we
- * tried processing it to generate a video preview on this client.
- *
- * Similar to [Note: Transient and permanent indexing failures], we attempt to
- * separate failures into two categories - transients, which leave no mark no
- * the DB so that the file eventually gets retried; and permanent, where we keep
- * a persistent record of failure so that this client does not go into a loop
- * reattempting preview generation for the specific unprocessable (to the best
- * of the current client's ability) item.
- *
- * The mark is local only, and will be reset on logout, or if another client
- * with a different able is able to process it.
- */
const markFailedVideoFile = async (file: EnteFile) => {
log.info(`Generate HLS for ${fileLogID(file)} | failed`);
const failedIDs = await savedFailedVideoFileIDs();
@@ -593,27 +257,11 @@ const markFailedVideoFile = async (file: EnteFile) => {
await saveFailedVideoFileIDs(failedIDs);
};
-/**
- * Return the persisted time when we last synced processed file IDs with remote.
- *
- * The returned value is an epoch millisecond value suitable to be passed to
- * {@link syncUpdatedFileDataFileIDs}.
- */
const savedSyncLastUpdatedAt = () => getKVN("videoPreviewSyncLastUpdatedAt");
-/**
- * Update the persisted timestamp used for syncing processed file IDs with
- * remote.
- *
- * Use {@link savedSyncLastUpdatedAt} to get the persisted value back.
- */
const saveSyncLastUpdatedAt = (lastUpdatedAt: number) =>
setKV("videoPreviewSyncLastUpdatedAt", lastUpdatedAt);
-/**
- * Fetch IDs of files from remote that have been processed by other clients
- * since the last time we checked.
- */
const pullProcessedFileIDs = async () =>
syncUpdatedFileDataFileIDs(
"vid_preview",
@@ -626,19 +274,6 @@ const pullProcessedFileIDs = async () =>
},
);
-/**
- * Remove any saved entries for file IDs which were previously in trash but now
- * have been permanently deleted.
- *
- * This is called when processing the trash diff. It gives us a hook to clear
- * these IDs from our video processing related local state.
- *
- * See: [Note: Pruning stale status-diff entries]
- *
- * It is a no-op when we're running in the context of the web app (since it
- * doesn't currently process videos, so doesn't need to keep any local state for
- * that purpose).
- */
export const videoPrunePermanentlyDeletedFileIDsIfNeeded = async (
deletedFileIDs: Set<number>,
) => {
@@ -653,63 +288,19 @@ export const videoPrunePermanentlyDeletedFileIDsIfNeeded = async (
}
};
-/**
- * If video processing is enabled, trigger a pull from remote and then proceed
- * with any subsequent backfill queue processing of pending videos.
- *
- * This function is intended to be called during a full remote pull (See: [Note:
- * Remote pull]). It is a no-op if video processing is not enabled or eligible
- * on this device. Otherwise it pulls the list of already processed file IDs
- * with remote.
- *
- * At this point it also triggers processing of the backfill (if needed), but
- * doesn't wait for it to complete (which might take a time for big libraries).
- *
- * Calling it when a backfill has already been triggered by a previous sync is
- * also a no-op. However, a backfill does not start until at least one pull of
- * file IDs has been completed with remote, to avoid picking up work on file IDs
- * that have already been processed elsewhere.
- */
export const videoProcessingSyncIfNeeded = async () => {
if (!isHLSGenerationSupported) return;
- // The `haveSyncedOnce` flag tracks whether or not a sync has happened for
- // the app, and is not specific to video processing. We always set it even
- // if HLS generation is currently disabled so that we can immediately start
- // processing the backfill if it gets video processing gets enabled during
- // the app's session, without waiting for the next sync to happen.
+ // Enabling generation later must not wait for another full sync.
_state.haveSyncedOnce = true;
if (!isHLSGenerationEnabled()) return;
await pullProcessedFileIDs();
- tickNow(); /* if not already ticking */
+ tickNow();
};
-/**
- * Create a streamable HLS playlist for a video uploaded from this client.
- *
- * This function is called by the uploader when it uploads a new file from this
- * client, allowing us to create its streamable variant without needing to
- * redownload the video.
- *
- * It only does the processing if we're running in the context of the desktop
- * app as the video processing is resource intensive. In particular, processing
- * large videos with the Wasm ffmpeg implementation can cause the app to crash,
- * on mobile devices (see https://github.com/ffmpegwasm/ffmpeg.wasm/issues/851).
- * In contrast, the desktop app can us the efficient native FFmpeg integration.
- *
- * Note that this function is an optimization. Even if we don't process the
- * video at this time (e.g. if the video processor can't keep up with the
- * uploads), we will eventually process it later as part of a backfill.
- *
- * @param file The {@link EnteFile} that got uploaded (video or otherwise).
- *
- * @param processableUploadItem The item that was uploaded. This can be used to
- * read the contents of the file that got uploaded directly from disk instead of
- * needing to download it again.
- */
export const processVideoNewUpload = (
file: EnteFile,
processableUploadItem: ProcessableUploadItem,
@@ -718,104 +309,42 @@ export const processVideoNewUpload = (
if (!isHLSGenerationEnabled()) return;
if (file.metadata.fileType != FileType.video) return;
if (processableUploadItem instanceof File) {
- // While the types don't guarantee it, we really shouldn't be getting
- // here. The only time a processableUploadItem can be File when we're
- // running in the desktop app is when an edited image copy is being
- // saved. But we've already checked above that the file which was
- // uploaded was a video.
assertionFailed();
return;
}
- // Enqueue the item.
_state.liveQueue.push({
file,
timestampedUploadItem: processableUploadItem,
});
- // Interrupt any idle timeouts if any, go go.
tickNow();
};
-/**
- * If {@link processQueue} is not already running, start it.
- *
- * If there is an existing {@link resolveTick} so that if perchance
- * {@link processQueue} was waiting on an idle timeout, it wakes up now.
- *
- * Also create a new {@link tick} and {@link resolveTick} pair for use by
- * subsequent calls to {@link tickNow}
- */
const tickNow = () => {
- // See: [Note: Exiting idle wait of processing loop] for what this function
- // is trying to do.
-
- // Resolve the existing tick (if any).
if (_state.resolveTick) _state.resolveTick();
- // Create a new resolvable pair.
_state.tick = new Promise((r) => (_state.resolveTick = r));
- // Start the processor if it isn't already running.
_state.queueProcessor ??= processQueue();
};
export const isHLSGenerationEnabled = () => _state.isHLSGenerationEnabled;
-/**
- * The video processing loop goes through videos one by one, preferring items in
- * the liveQueue, otherwise working for a backlog item. If there are no items to
- * process, it goes on an idle timeout. The {@link resolveTick} state property
- * can be used to tickle it out of sleep.
- *
- * [Note: Exiting idle wait of processing loop]
- *
- * The following toy example illustrates the overall mechanism:
- *
- * let resolveTick
- * let tick = new Promise((r) => (resolveTick = r));
- *
- * const tickNow = () => {
- * resolveTick();
- * tick = new Promise((r) => (resolveTick = r));
- * }
- *
- * const f = async () => {
- * for (let i of [1, 2, 3, 4, 5]) {
- * const wait = new Promise((r) => setTimeout(r, i * 1e3));
- * await Promise.race([wait, tick]);
- * }
- * }
- *
- * f()
- *
- * setTimeout(tickNow, 2500);
- * setTimeout(tickNow, 5000);
- * setTimeout(tickNow, 5500);
- *
- * The `Promise.race([wait, tick])` means that the loop will proceed to the next
- * item either if the timeout expires, or if tick resolves. Thus the same
- * function can handle both the internally determined processing of backfill
- * batches, and the externally triggered processing of live uploads.
- */
const processQueue = async () => {
if (!isHLSGenerationSupported || !isHLSGenerationEnabled()) {
- assertionFailed(); /* we shouldn't have come here */
+ assertionFailed();
return;
}
const userID = ensureLocalUser().id;
- // We mark failures in the local DB for in expected failure mode. As an
- // additional protection against loops in unforeseen scenarios, keep a
- // transient in-memory list of IDs which shouldn't be looped.
const transientFailedFileIDs = new Set<number>();
let bq: typeof _state.liveQueue | undefined;
while (isHLSGenerationEnabled()) {
let item = _state.liveQueue.shift();
if (!item) {
- // Initialize or refill queue.
if (!bq?.length) {
if (_state.haveSyncedOnce) {
bq = await backfillQueue(userID);
@@ -823,7 +352,6 @@ const processQueue = async () => {
log.info("Not attempting backfill until first sync");
}
}
- // Take item if queue is not empty.
if (bq?.length) item = bq.pop();
}
if (item && !transientFailedFileIDs.has(item.file.id)) {
@@ -832,24 +360,17 @@ const processQueue = async () => {
try {
await processQueueItem(item);
await markProcessedVideoFileID(item.file.id);
- // Reset the idle wait on success.
_state.idleWait = idleWaitInitial;
} catch (e) {
- // This will get retried again at some point later.
log.error(`Failed to process video ${fileLogID(item.file)}`, e);
transientFailedFileIDs.add(item.file.id);
}
} else {
- // There are no more items in either the live queue or backlog.
- // Go to sleep (for increasingly longer durations, capped at a
- // maximum).
updateSnapshotIfNeeded("idle");
const idleWait = _state.idleWait;
_state.idleWait = Math.min(idleWait * 2, idleWaitMax);
- // `tick` allows the sleep to be interrupted when there is
- // potential activity.
if (!_state.tick) assertionFailed();
const tick = _state.tick!;
@@ -863,14 +384,6 @@ const processQueue = async () => {
_state.queueProcessor = undefined;
};
-/**
- * Return the next batch of videos that need to be processed.
- *
- * If there is nothing pending, return an empty array.
- *
- * @param userID The ID of the currently logged in user. This is used to filter
- * the files to only include those that are owned by the user.
- */
const backfillQueue = async (
userID: number,
): Promise<VideoProcessingQueueItem[]> => {
@@ -879,13 +392,9 @@ const backfillQueue = async (
const videoFiles = uniqueFilesByID(
allCollectionFiles.filter(
(f) =>
- // Only files the user owns.
f.ownerID == userID &&
- // Only videos.
f.metadata.fileType == FileType.video &&
- // Not in trash.
!localTrashFileIDs.has(f.id) &&
- // See: [Note: Marking files which do not need video processing]
f.pubMagicMetadata?.data.sv != 1,
),
);
@@ -899,25 +408,6 @@ const backfillQueue = async (
return batch.map((file) => ({ file }));
};
-/**
- * Generate and upload a streamable variant of the given {@link EnteFile}.
- *
- * [Note: Preview variant of videos]
- *
- * A preview variant of a video is created by transcoding it into a smaller,
- * streamable, and (more) widely supported format.
- *
- * 1. The video is transcoded into a format that is both smaller but is also
- * using a much more widely supported codec so that it can be played back
- * readily across browsers and OSes independent of the codec used by the
- * source video.
- *
- * 2. We use a format that can be streamed back by the client instead of needing
- * to download it all at once, and also generate an HLS playlist that refers
- * to the offsets in the generated video file.
- *
- * 3. Both the generated video and the HLS playlist are then uploaded, E2EE.
- */
const processQueueItem = async ({
file,
timestampedUploadItem,
@@ -928,12 +418,7 @@ const processQueueItem = async ({
const playlistFileData = await fetchFileData("vid_preview", file.id);
if (playlistFileData) {
- // Since video processing for even an individual item can take
- // substantial time, it is possible that an item might've gotten
- // processed on a different client in the interval between us enqueuing
- // it and us getting here.
- //
- // Bail out early to avoid unnecessary duplicate work.
+ // Queue delay may have let another client finish this file first.
log.info(`Generate HLS for ${fileLogID(file)} | already-processed`);
return;
}
@@ -958,38 +443,7 @@ const processQueueItem = async ({
}
}
- // [Note: Upload HLS video segment from node side]
- //
- // The generated video can be huge (multi-GB), too large to read it into
- // memory as an arrayBuffer.
- //
- // One option was to chain the video stream response (from the node side)
- // directly into a fetch request to `objectUploadURL`, however that requires
- // HTTP/2 (our servers support it, but self hosters' might not). Also that
- // approach won't work with retries on transient failures unless we
- // duplicate the stream beforehand, which invalidates the point of
- // streaming.
- //
- // Another mid-way option was to do it partially here - obtain the pre-signed
- // upload URLs here (since we already have the rest of the scaffolding to
- // make API requests), and then provide this pre-signed URL to the node side
- // so that it can directly upload the generated video segments.
- //
- // However, that then gets into a issue for multipart uploads since we don't
- // know the size of the generated HLS video segment file beforehand. We can
- // try to estimate it, and that is indeed what we started off with, and that
- // approach worked fine too.
- //
- // However, estimates being estimates, it felt better to make things more
- // deterministic by moving the request for the pre-signed URLs also to the
- // desktop app side. This also sidesteps the issue of passing along too much
- // data (the multipart upload URLs) as request params to the desktop app.
- // There was no specific issue again, it just felt that doing everything in
- // the desktop app is more simple and straightforward (at the cost of
- // needing set up of some API request scaffolding on the desktop side).
- //
- // Below we prepare the things that we need to pass to the desktop app to
- // allow it to make the API request for obtaining pre-signed upload URLs.
+ // Generated segments can be multi-GB, so native owns both upload and retries.
const fetchURL = await apiURL("/files/data/preview-upload-url");
const authToken = await ensureAuthToken();
@@ -1022,7 +476,7 @@ const processQueueItem = async ({
if (!res) {
log.info(`Generate HLS for ${fileLogID(file)} | not-required`);
- // See: [Note: Marking files which do not need video processing]
+ // Persist stable ineligibility so every client can skip this file.
await updateFilePublicMagicMetadata(file, { sv: 1 });
return;
}
@@ -1060,12 +514,5 @@ const processQueueItem = async ({
}
};
-/**
- * A semi-sibling of {@link decryptPlaylistJSON}, which does the gzip but leaves
- * the encryption up to the next layer.
- *
- * It is a trivial function, the main utility it provides is that it forces us
- * to conform to the {@link PlaylistJSON} type.
- */
const encodePlaylistJSON = (playlistJSON: PlaylistJSON) =>
gzip(JSON.stringify(playlistJSON));
diff --git a/web/packages/new/photos/services/app-lock.ts b/web/packages/new/photos/services/app-lock.ts
index 78d849496c..bcff68878d 100644
--- a/web/packages/new/photos/services/app-lock.ts
+++ b/web/packages/new/photos/services/app-lock.ts
@@ -1,14 +1,3 @@
-/**
- * @file Service for the app lock feature.
- *
- * App lock is a purely client-side feature that prevents unauthorized access to
- * the app after it has been authenticated. It supports PIN, password, and
- * local native device lock (macOS Touch ID), and uses Argon2id for passphrase
- * hashing.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
-
import { deriveInteractiveKey, deriveKey } from "ente-base/crypto";
import {
clearMainWindowBlurSuppression,
@@ -24,28 +13,14 @@ import type {
PersistedAppLockConfig,
} from "ente-base/types/ipc";
-/**
- * In-memory state for the app lock feature.
- *
- * Desktop config is persisted only in Electron safe storage, while passphrase
- * and brute-force state live in IndexedDB via KV DB.
- */
export interface AppLockState {
- /** Whether app lock is supported in the current desktop environment. */
supported: boolean;
- /** Whether app lock is enabled. */
enabled: boolean;
- /** Active lock type. */
lockType: "pin" | "password" | "device" | "none";
- /** Why the lock screen is currently shown. */
lockScreenMode: "lock" | "reauthenticate";
- /** Whether the app is currently locked. */
isLocked: boolean;
- /** Consecutive failed attempts in current lockout cycle. */
invalidAttemptCount: number;
- /** Epoch ms when cooldown expires (0 = no cooldown). */
cooldownExpiresAt: number;
- /** Auto-lock delay in milliseconds. */
autoLockTimeMs: number;
}
@@ -60,30 +35,16 @@ const createDefaultState = (): AppLockState => ({
autoLockTimeMs: 0,
});
-/**
- * Internal in-memory state shared by the functions in this module.
- *
- * This entire object will be reset on logout.
- */
+// Config lives in Electron safe storage; hashes and lockout state live in KV.
class AppLockModuleState {
constructor() {
this.snapshot = createDefaultState();
}
- /**
- * Subscriptions to {@link AppLockState} updates attached using
- * {@link appLockSubscribe}.
- */
listeners: (() => void)[] = [];
-
- /**
- * Snapshot of the {@link AppLockState} returned by
- * {@link appLockSnapshot}.
- */
snapshot: AppLockState;
}
-/** State shared by the functions in this module. */
let _state: AppLockModuleState | undefined;
let _bruteForceStateHydration = Promise.resolve();
let _bruteForceStateHydrationGeneration = 0;
@@ -94,15 +55,6 @@ const appLockState = () => {
return _state;
};
-/**
- * Subscribe to updates to {@link AppLockState}.
- *
- * The callback is invoked whenever {@link setSnapshot} updates
- * {@link _state.snapshot}. Returns an unsubscribe function that removes the
- * callback from the listener list.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
export const appLockSubscribe = (onChange: () => void): (() => void) => {
const state = appLockState();
state.listeners.push(onChange);
@@ -111,22 +63,8 @@ export const appLockSubscribe = (onChange: () => void): (() => void) => {
};
};
-/**
- * Return the last known, cached {@link AppLockState}.
- *
- * See also {@link appLockSubscribe}.
- */
export const appLockSnapshot = () => appLockState().snapshot;
-/**
- * Update the internal app lock state snapshot and notify all subscribers.
- *
- * This is the single source of truth for state updates. All modifications to
- * _state.snapshot must go through this function to ensure subscribers are
- * properly notified of changes.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
const setSnapshot = (snapshot: AppLockState) => {
const state = appLockState();
state.snapshot = snapshot;
@@ -138,8 +76,6 @@ const setSnapshot = (snapshot: AppLockState) => {
const ssKeySuppressNextSessionRefreshLock =
"appLock.suppressNextSessionRefreshLock";
-// -- KV DB keys (IndexedDB, async) --
-
const kvKeyHash = "appLock.hash";
const kvKeySalt = "appLock.salt";
const kvKeyOpsLimit = "appLock.opsLimit";
@@ -147,8 +83,6 @@ const kvKeyMemLimit = "appLock.memLimit";
const kvKeyInvalidAttempts = "appLock.invalidAttempts";
const kvKeyCooldownExpiresAt = "appLock.cooldownExpiresAt";
-// -- Device lock constants --
-
const deviceLockEnablePromptReason = "enable device lock";
const deviceLockUnlockPromptReason = "unlock";
const maxInvalidUnlockAttempts = 10;
@@ -157,33 +91,19 @@ const cooldownBaseSeconds = 30;
const unlockAttemptLockName = "ente-app-lock-unlock-attempt";
const trustedPromptAutoLockSuppressionMs = 5 * 1e3;
-/**
- * Temporarily suppress auto-lock on blur for trusted app-initiated prompts.
- *
- * This is used for native device authentication prompts that can transiently
- * blur the app window even though the user hasn't backgrounded the app.
- */
export const suppressAutoLockOnBlurForTrustedPrompt = () => {
suppressMainWindowBlurForTrustedPrompt(trustedPromptAutoLockSuppressionMs);
};
-/**
- * Return true if blur-triggered auto-lock should currently be suppressed.
- */
export const shouldSuppressAutoLockOnBlur = () =>
shouldSuppressMainWindowBlur();
-/**
- * Clear any pending blur auto-lock suppression.
- */
export const clearAutoLockBlurSuppression = () => {
clearMainWindowBlurSuppression();
};
-/**
- * Suppress one app-lock refresh cycle after a trusted app-initiated reload.
- */
export const suppressAppLockRefreshFromSessionForTrustedReload = () => {
+ // This session flag is consumed by exactly one refresh.
try {
if (!appLockSnapshot().enabled) return;
sessionStorage.setItem(ssKeySuppressNextSessionRefreshLock, "true");
@@ -204,7 +124,6 @@ const consumeAppLockRefreshSuppressionFromSession = () => {
sessionStorage.removeItem(ssKeySuppressNextSessionRefreshLock);
return true;
} catch {
- // Ignore storage read errors; fallback to regular app-lock behavior.
return false;
}
};
@@ -232,13 +151,8 @@ const logDeviceLockEvent = (
log.warn(message, { reason });
};
-/**
- * Return the cooldown duration for a failed-attempt count.
- *
- * This policy is shared by lockout enforcement and cooldown UI (used by the
- * app lock screen to render countdown progress).
- */
export const appLockCooldownDurationMs = (attemptCount: number): number => {
+ // The lock screen and enforcement must use the same cooldown policy.
if (attemptCount < cooldownStartsAtAttempt) return 0;
return (
Math.pow(2, attemptCount - cooldownStartsAtAttempt) *
@@ -272,15 +186,6 @@ const readBruteForceStateFromKV = async () => {
};
};
-/**
- *
- * @param value the autoLockTimeMS
- * @returns clampedNonNegativeFinite integer value
- *
- * So this function is bascially a normalization function, to update the
- * value of the autoLockTimeMs in case it becomes any non-negative/non-finite
- * number like -4 or NaN in-case of some corruption or unexpected case.
- */
const clampNonNegativeInt = (value: number) =>
Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
@@ -290,17 +195,6 @@ const defaultPersistedAppLockConfig = (): PersistedAppLockConfig => ({
autoLockTimeMs: 0,
});
-/**
- * Validates and retrieves the Electron app lock API from the global scope.
- *
- * Checks if the Electron API is available and has all required app lock
- * related functions before returning it. This ensures safe access to
- * Electron's secure storage capabilities for app lock configuration.
- *
- * @returns {Object | undefined} The Electron API object with app lock methods
- * if all required functions are available,
- * otherwise undefined.
- */
const appLockElectron = () => {
const electron = globalThis.electron;
if (
@@ -368,12 +262,6 @@ const clearPersistedAppLockConfig = async () => {
await electron.clearAppLockConfigFromSafeStorage();
};
-/**
- * Update in-memory app-lock state from persisted config.
- *
- * Used during `initAppLock` (cold start) and
- * `refreshAppLockStateFromSession` (after session restore).
- */
const setSnapshotFromPersistedConfig = (
config: PersistedAppLockConfig,
isLocked: boolean,
@@ -394,11 +282,6 @@ const setSnapshotFromPersistedConfig = (
let _localUnlockAttemptQueue = Promise.resolve();
-/**
- * Serialize unlock attempts within the current tab.
- *
- * This fallback mutex is used when the Web Locks API is unavailable.
- */
const withLocalUnlockAttemptLock = async <T>(fn: () => Promise<T>) => {
const previous = _localUnlockAttemptQueue;
let releaseCurrent: (() => void) | undefined;
@@ -415,13 +298,8 @@ const withLocalUnlockAttemptLock = async <T>(fn: () => Promise<T>) => {
}
};
-/**
- * Serialize unlock attempts across tabs when possible.
- *
- * Uses the Web Locks API for cross-tab mutual exclusion, and falls back to
- * {@link withLocalUnlockAttemptLock} when unavailable.
- */
const withUnlockAttemptLock = async <T>(fn: () => Promise<T>) => {
+ // Web Locks serialize counters across tabs; the fallback covers this tab.
const locks =
typeof navigator == "undefined"
? undefined
@@ -439,19 +317,6 @@ const withUnlockAttemptLock = async <T>(fn: () => Promise<T>) => {
return withLocalUnlockAttemptLock(fn);
};
-// -- Public API --
-
-/**
- * Initialize app lock state from persistent storage on cold start.
- *
- * On desktop, this restores the config from Electron safe storage before
- * gating rendering, then locks pessimistically while session hydration is in
- * flight.
- *
- * After the initial snapshot, asynchronously restores the brute-force
- * attempt count and cooldown expiry from KV DB so that a page refresh cannot
- * bypass the cooldown.
- */
export const initAppLock = async () => {
if (!appLockElectron()) {
setSnapshot(createDefaultState());
@@ -479,16 +344,10 @@ export const initAppLock = async () => {
return;
}
+ // Lock before session hydration, then restore persisted brute-force state.
setSnapshotFromPersistedConfig(config, config.enabled, true);
};
-/**
- * Restore the brute-force attempt count and cooldown expiry from KV DB into
- * the in-memory snapshot.
- *
- * Called during {@link initAppLock} to ensure that cooldown timers persist
- * across page refreshes.
- */
const restoreBruteForceState = async (generation: number) => {
try {
const { invalidAttemptCount, cooldownExpiresAt } =
@@ -534,8 +393,6 @@ const unsupportedNativeDeviceLockCapability: NativeDeviceLockCapability = {
const nativeDeviceLockCapability =
async (): Promise<NativeDeviceLockCapability> => {
- // Native device lock is available only in the desktop (Electron) app.
- // On web, we always treat it as unsupported.
if (!globalThis.electron) return unsupportedNativeDeviceLockCapability;
try {
@@ -576,22 +433,13 @@ const resolveDeviceLockCapability = async (): Promise<DeviceLockCapability> => {
const reason = nativeCapabilityUnavailableReason(nativeCapability);
if (reason === "touchid-temporarily-unavailable") {
- // Keep unlock/setup retryable on macOS even when capability checks are
- // briefly inconclusive.
+ // Keep setup retryable while macOS reports a transient failure.
return { usable: true, mode: "native" };
}
return { usable: false, reason };
};
-/**
- * Return true if the current environment should show "Device lock" in the
- * lock-type picker.
- *
- * We show it when native auth is currently available, or when the platform
- * supports it but setup/auth is temporarily unavailable (for example, Touch ID
- * not enrolled).
- */
export const shouldShowDeviceLockOption = async () => {
if (!appLockSnapshot().supported) return false;
@@ -611,12 +459,6 @@ const clearPassphraseMaterial = async () =>
removeKV(kvKeyMemLimit),
]);
-/**
- * Reset brute-force protection state.
- *
- * Clears persisted invalid-attempt and cooldown values in KV and updates the
- * in-memory snapshot to zero.
- */
const resetBruteForceState = async () => {
await Promise.all([
setKV(kvKeyInvalidAttempts, 0),
@@ -641,12 +483,6 @@ const unlockLocally = () => {
stopBruteForceStateHydration();
};
-/**
- * Cancel an in-progress explicit reauthentication prompt.
- *
- * This only dismisses the reauthentication lock screen, allowing callers of
- * {@link reauthenticateWithAppLock} to fall back to alternate auth flows.
- */
export const cancelReauthentication = () => {
const snapshot = appLockState().snapshot;
if (!snapshot.isLocked || snapshot.lockScreenMode !== "reauthenticate") {
@@ -658,12 +494,6 @@ export const cancelReauthentication = () => {
stopBruteForceStateHydration();
};
-/**
- * Recompute and refresh whether the app should currently be locked based on
- * session availability.
- *
- * Call this after desktop safe-storage restore to prevent auto-login bypass.
- */
export const refreshAppLockStateFromSession = async () => {
if (!(await isAppLockSupported())) {
if (appLockSnapshot().enabled) {
@@ -688,24 +518,11 @@ export const refreshAppLockStateFromSession = async () => {
setSnapshotFromPersistedConfig(config, isLocked, true);
};
-/**
- * The result of a device lock setup attempt.
- *
- * - `success` - Device lock setup completed and app lock configured.
- * - `not-supported` - Platform authenticator is unavailable in this context.
- * - `failed` - Setup failed or was cancelled by the user.
- */
export type SetupDeviceLockResult =
| { status: "success"; mode: DeviceLockMode }
| { status: "not-supported"; reason: NativeDeviceLockUnavailableReason }
| { status: "failed"; reason: DeviceLockFailureReason };
-/**
- * Set up a PIN for app lock.
- *
- * Derives a key from the PIN using Argon2id with interactive limits, stores
- * the hash and derivation parameters in KV DB, and enables the lock.
- */
const setupPassphraseLock = async (
lockType: Extract<AppLockState["lockType"], "pin" | "password">,
input: string,
@@ -741,39 +558,25 @@ const setupPassphraseLock = async (
export const setupPin = async (pin: string) => setupPassphraseLock("pin", pin);
-/**
- * Set up a password for app lock.
- *
- * Same as {@link setupPin} but sets the lock type to "password".
- */
export const setupPassword = async (password: string) =>
setupPassphraseLock("password", password);
-/**
- * Set up native device lock authentication for app lock (macOS only).
- */
export const setupDeviceLock = async (): Promise<SetupDeviceLockResult> => {
if (!(await isAppLockSupported())) {
return { status: "failed", reason: "unknown" };
}
- // Resolve whether native device lock is currently usable in this environment.
- // Flow: resolveDeviceLockCapability() -> nativeDeviceLockCapability() ->
- // globalThis.electron.getNativeDeviceLockCapability().
const capability = await resolveDeviceLockCapability();
- // Surface unsupported reasons to callers/UI.
if (!capability.usable) {
logDeviceLockEvent("setup", "not-supported", capability.reason);
return { status: "not-supported", reason: capability.reason };
}
try {
- // Ignore blur auto-lock caused by this trusted, app-initiated native
- // prompt.
+ // The native prompt blurs the window but must not auto-lock it.
suppressAutoLockOnBlurForTrustedPrompt();
- // Trigger the OS-native authentication prompt (for example, Touch ID).
const unlocked = await globalThis.electron?.promptDeviceLock(
deviceLockEnablePromptReason,
);
@@ -782,10 +585,8 @@ export const setupDeviceLock = async (): Promise<SetupDeviceLockResult> => {
return { status: "failed", reason: "native-prompt-failed" };
}
- // Reset brute-force lockout/cooldown state in KV and in memory.
await resetBruteForceState();
- // Update the in-memory app-lock snapshot.
const snapshot = appLockState().snapshot;
await savePersistedAppLockConfig({
enabled: true,
@@ -800,7 +601,6 @@ export const setupDeviceLock = async (): Promise<SetupDeviceLockResult> => {
cooldownExpiresAt: 0,
});
- // Stop ongoing brute-force hydration.
stopBruteForceStateHydration();
return { status: "success", mode: "native" };
@@ -810,27 +610,13 @@ export const setupDeviceLock = async (): Promise<SetupDeviceLockResult> => {
}
};
-/**
- * The result of an unlock attempt.
- *
- * - `"success"` - The input was correct; the app is now unlocked.
- * - `"failed"` - The input was incorrect.
- * - `"cooldown"` - Too many recent attempts; currently in cooldown.
- * - `"logout"` - Too many total attempts (>= 10); caller should force logout.
- */
export type UnlockResult = "success" | "failed" | "cooldown" | "logout";
-/**
- * The result of a device lock unlock attempt.
- */
export type DeviceLockUnlockResult =
| { status: "success"; mode: DeviceLockMode }
| { status: "not-supported"; reason: NativeDeviceLockUnavailableReason }
| { status: "failed"; reason: DeviceLockFailureReason };
-/**
- * Attempt to unlock the app using native device lock (macOS only).
- */
export const attemptDeviceLockUnlock =
async (): Promise<DeviceLockUnlockResult> => {
const capability = await resolveDeviceLockCapability();
@@ -857,18 +643,7 @@ export const attemptDeviceLockUnlock =
}
};
-/**
- * Attempt to unlock the app with the given PIN or password.
- *
- * Implements brute-force protection: after 5 failed attempts, a cooldown
- * period is enforced (exponential backoff starting at 30s). After 10 failed
- * attempts, signals that the caller should force-logout the user.
- */
export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
- /**
- * This flow applies only to PIN and password locks.
- * Guard against being called for any other lock type.
- */
const snapshot = appLockState().snapshot;
const isPassphraseLock =
snapshot.lockType === "pin" || snapshot.lockType === "password";
@@ -877,15 +652,9 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
}
return withUnlockAttemptLock<UnlockResult>(async () => {
- // Ensure persisted lockout state has been rehydrated before enforcing.
await ensureBruteForceStateHydrated();
- /**
- * Refresh lockout state from KV so stale tabs cannot reset counters.
- *
- * If multiple tabs attempt to unlock at the same time, sync from KV DB
- * before validation so all tabs use the latest attempt/cooldown state.
- */
+ // Merge with KV so a stale tab cannot lower another tab's counters.
const persistedState = await readBruteForceStateFromKV();
const latestSnapshot = appLockState().snapshot;
const invalidAttemptCount = Math.max(
@@ -897,7 +666,6 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
persistedState.cooldownExpiresAt,
);
- // Update the snapshot with the latest values.
setBruteForceSnapshot(invalidAttemptCount, cooldownExpiresAt);
if (invalidAttemptCount >= maxInvalidUnlockAttempts) {
@@ -906,7 +674,6 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
return "logout";
}
- // Check cooldown from in-memory state.
const snapshotWithCooldown = appLockState().snapshot;
if (
snapshotWithCooldown.cooldownExpiresAt > 0 &&
@@ -915,7 +682,6 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
return "cooldown";
}
- // Read stored derivation parameters and hash from KV DB.
const salt = await getKVS(kvKeySalt);
const storedHash = await getKVS(kvKeyHash);
const opsLimit = await getKVN(kvKeyOpsLimit);
@@ -926,35 +692,28 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
return "failed";
}
- // Derive key from input using the stored parameters.
const derivedKey = await deriveKey(input, salt, opsLimit, memLimit);
if (derivedKey === storedHash) {
- // Correct input: reset attempts, unlock.
await resetBruteForceState();
unlockLocally();
return "success";
}
- // Incorrect input: increment attempts.
const count = invalidAttemptCount + 1;
await setKV(kvKeyInvalidAttempts, count);
if (count >= maxInvalidUnlockAttempts) {
- // Too many attempts: signal logout.
await setKV(kvKeyCooldownExpiresAt, 0);
setBruteForceSnapshot(count, 0);
return "logout";
}
if (count >= cooldownStartsAtAttempt) {
- // Enforce cooldown with exponential backoff.
const expiresAt = Date.now() + appLockCooldownDurationMs(count);
await setKV(kvKeyCooldownExpiresAt, expiresAt);
setBruteForceSnapshot(count, expiresAt);
- // The current failed attempt has triggered cooldown, so surface the
- // cooldown state immediately to callers/UI.
return "cooldown";
} else {
setBruteForceSnapshot(count, 0);
@@ -964,14 +723,6 @@ export const attemptUnlock = async (input: string): Promise<UnlockResult> => {
});
};
-/**
- * Perform an explicit reauthentication using app lock.
- *
- * - `"authenticated"` when app lock reauthentication succeeds.
- * - `"cancelled"` when the user dismisses the reauthentication prompt.
- * - `"fallback"` when app lock is unavailable or cannot be started, so callers
- * can use an alternate auth flow (for example, master password prompt).
- */
export type ReauthenticateWithAppLockResult =
| "authenticated"
| "cancelled"
@@ -985,8 +736,7 @@ export const reauthenticateWithAppLock =
let canUseAppLock =
snapshot.enabled && snapshot.lockType !== "none";
if (canUseAppLock && snapshot.lockType === "device") {
- // For device lock, ensure native auth is actually usable right now.
- // If unavailable (e.g. Touch ID disabled), fall back to password flow.
+ // Let callers fall back to password if native auth is unavailable.
const capability = await resolveDeviceLockCapability();
canUseAppLock = capability.usable;
}
@@ -1021,9 +771,6 @@ export const reauthenticateWithAppLock =
}
};
-/**
- * Lock the app.
- */
export const lock = (
lockScreenMode: AppLockState["lockScreenMode"] = "lock",
) => {
@@ -1032,12 +779,6 @@ export const lock = (
hydrateBruteForceStateIfNeeded();
};
-/**
- * Clear all app lock data on logout.
- *
- * Removes all persisted config and KV DB keys, and resets in-memory state to
- * defaults.
- */
export const logoutAppLock = async () => {
if (appLockElectron()) {
await clearPersistedAppLockConfig();
@@ -1054,9 +795,6 @@ export const logoutAppLock = async () => {
_state = undefined;
};
-/**
- * Update the auto-lock delay.
- */
export const setAutoLockTime = async (ms: number) => {
if (!(await isAppLockSupported())) {
throw new Error("App lock is not supported");
@@ -1072,12 +810,6 @@ export const setAutoLockTime = async (ms: number) => {
setSnapshot({ ...snapshot, autoLockTimeMs });
};
-/**
- * Disable app lock entirely.
- *
- * Clears all stored credentials from KV DB, resets attempts and cooldown, and
- * updates persisted config and in-memory state.
- */
export const disableAppLock = async () => {
if (!(await isAppLockSupported())) {
throw new Error("App lock is not supported");
diff --git a/web/packages/new/photos/services/collection-summary.ts b/web/packages/new/photos/services/collection-summary.ts
index 8746d20c0c..4b919f4c00 100644
--- a/web/packages/new/photos/services/collection-summary.ts
+++ b/web/packages/new/photos/services/collection-summary.ts
@@ -26,153 +26,33 @@ export type CollectionSummaryAttribute =
| "pinned"
| "shareePinned";
-/**
- * ID of the special {@link CollectionSummary} instances that are not backed by
- * a real {@link Collection}.
- */
export const PseudoCollectionID = {
- /**
- * The "All" section.
- *
- * The "All" section is the default view when the user opens the gallery,
- * showing them all of their unique non-hidden and non-archived files.
- */
all: 0,
- /**
- * A pseudo-collection containing the individually archived files.
- *
- * The archive items is a pseudo-collection consisting of all the files
- * which have been individually archived. It is what gets shown when the
- * user navigates to the "Archive" section.
- */
archiveItems: -1,
- /**
- * Trash.
- *
- * This pseudo-collection contains items that are in the user's trash. Each
- * items corresponds to a file that has been deleted, but has not yet been
- * deleted permanently.
- *
- * As a special case, when the trash pseudo collection is being shown, then
- * the corresponding files array will have {@link EnteTrashFile} items
- * instead of normal {@link EnteFile} ones.
- */
+ // Trash summaries carry EnteTrashFile entries instead of EnteFile.
trash: -2,
- /**
- * A placeholder for the uncategorized collection until the real one comes
- * into existence.
- *
- * [Note: Uncategorized placeholder]
- *
- * The user's sole "uncategorized" collection is created on demand the first
- * time we need to move a file out of the last collection it belonged to
- * (yet retain the file).
- *
- * Until the real uncategorized collection comes into existence, we use this
- * dummy placeholder collection as the {@link CollectionSummary} that gets
- * shown if the user navigates to the "Uncategorized" section in the UI.
- */
+ // This stands in until the on-demand Uncategorized collection is created.
uncategorizedPlaceholder: -3,
- /**
- * A pseudo-collection containing the individually hidden files.
- *
- * The "Hidden items" is the default pseudo-collection shown in the "Hidden"
- * section. It consists of the files that the user has individually hidden.
- *
- * It is derived by merging all of the user's "default hidden" albums (See:
- * Note: Multiple "default" hidden collections]).
- *
- * In addition to this "Hidden items" pseudo-collection, the "Hidden"
- * section also shows other albums that were hidden.
- */
+ // Hidden items merges every default-hidden collection.
hiddenItems: -4,
} as const;
-/**
- * A massaged version of a collection or a pseudo-collection suitable for being
- * directly shown in the UI.
- *
- * From one perspective, this can be thought of as a
- * "CollectionOrPseudoCollection": a group of files listed together in the UI,
- * with the files coming from a real "collection" or some special "section".
- *
- * - In the first case, the underlying listing will be backed by a
- * {@link Collection},
- *
- * - In the second case the files and other attributes comprising the listing
- * will be determined by the special case-specific rules for that particular
- * pseudo-collection.
- *
- * However, even when this is backed by a corresponding "real"
- * {@link Collection}, it adds some extra attributes that make it easier and
- * more efficient for the UI elements to render this collection summary
- * directly. So from that perspective, this can be also be thought of as a
- * "UICollection".
- */
export interface CollectionSummary {
- /**
- * The ID of the underlying {@link Collection}, or one of the predefined
- * {@link PseudoCollectionID}s.
- */
id: number;
- /**
- * The primary "UI" type for the collection or pseudo-collection.
- *
- * For newer code consider using {@link attributes} instead.
- */
type: CollectionSummaryType;
- /**
- * Various UI related attributes of the collection or pseudo-collection.
- *
- * This is meant to replace {@link type} gradually. It defines various
- * ad-hoc "UI" attributes which make it easier and more efficient for the UI
- * elements to render the collection summary in the UI.
- */
attributes: Set<CollectionSummaryAttribute>;
- /**
- * The name of the collection or pseudo-collection surfaced in the UI.
- */
name: string;
- /**
- * The newest file in the collection or pseudo-collection (if any).
- */
latestFile: EnteFile | undefined;
- /**
- * The file to show as the cover for the collection or pseudo-collection.
- *
- * This can be one of
- * - A file explicitly chosen by the user.
- * - The latest file.
- * - The oldest file (if the user has set a reverse sort on the collection).
- */
coverFile: EnteFile | undefined;
- /**
- * The number of files in the underlying collection, or the number of files
- * computed to belong to the pseudo-collection.
- */
fileCount: number;
- /**
- * The time (epoch microseconds) when the collection was last updated. For
- * pseudo-collections this will (usually) be the updation time of the latest
- * file that it contains.
- */
+ // Epoch microseconds.
updationTime: number | undefined;
sortPriority: CollectionSummarySortPriority;
order?: number;
}
-/**
- * Collection summaries, indexed by their IDs.
- */
export type CollectionSummaries = Map<number, CollectionSummary>;
-/**
- * The sort schemes that can be used when we're showing list of collections
- * (e.g. in the collection bar).
- *
- * This is the list of all possible values, see {@link CollectionsSortBy} for
- * the type.
- */
export const collectionsSortBy = [
"name-asc",
"name-desc",
@@ -182,36 +62,16 @@ export const collectionsSortBy = [
"updation-time-desc",
] as const;
-/**
- * Type of individual {@link collectionsSortBy} values.
- */
export type CollectionsSortBy = (typeof collectionsSortBy)[number];
-/**
- * An orderable set collection "priorities".
- *
- * Collection summaries that need to appear prior to other collection summaries
- * get assigned a "priority", which is an otherwise arbitrary integer that only
- * serves as a sort priority (higher being prior).
- *
- * All collections in a higher category appear together, and before collections
- * in lower categories. Within each priority, the collections are sorted by the
- * applicable {@link CollectionsSortBy}.
- */
+// Higher priorities render first.
export const CollectionSummarySortPriority = {
- /**
- * Currently: "All", "Uncategorized", "Hidden items".
- */
system: 9,
favorites: 8,
pinned: 7,
other: 0,
} as const;
-/**
- * The TypeScript type that restricts the possible values to be one from amongst
- * the {@link CollectionSummarySortCategory} constants.
- */
export type CollectionSummarySortPriority =
(typeof CollectionSummarySortPriority)[keyof typeof CollectionSummarySortPriority];
@@ -228,17 +88,11 @@ export const canAddToCollection = ({ attributes }: CollectionSummary) =>
export const canMoveToCollection = ({ attributes }: CollectionSummary) =>
!attributes.has("system") && !attributes.has("sharedIncoming");
-/**
- * Sort an array of collection summaries by the specified sort order.
- *
- * @param collectionSummaries The array of collection summaries to sort
- * @param by The sort order to apply
- * @returns A new sorted array of collection summaries
- */
export const sortCollectionSummaries = (
collectionSummaries: CollectionSummary[],
by: CollectionsSortBy,
): CollectionSummary[] => {
+ // Collection IDs increase with creation time.
return [...collectionSummaries].sort((a, b) => {
switch (by) {
case "name-asc":
@@ -246,10 +100,8 @@ export const sortCollectionSummaries = (
case "name-desc":
return b.name.localeCompare(a.name);
case "creation-time-asc":
- // Oldest first: lower ID = created earlier.
return a.id - b.id;
case "creation-time-desc":
- // Newest first: higher ID = created later.
return b.id - a.id;
case "updation-time-asc":
return (a.updationTime ?? 0) - (b.updationTime ?? 0);
diff --git a/web/packages/new/photos/services/collection.ts b/web/packages/new/photos/services/collection.ts
index dc308ceb0c..bb5b0adcb7 100644
--- a/web/packages/new/photos/services/collection.ts
+++ b/web/packages/new/photos/services/collection.ts
@@ -59,53 +59,18 @@ export const defaultHiddenCollectionUserFacingName = "Hidden";
const favoritesCollectionName = "Favorites";
const copyRequestBatchSize = 100;
-/**
- * Create a new album (a collection of type "album") on remote, and return its
- * local representation.
- *
- * Remote only, does not modify local state.
- *
- * @param albumName The name to use for the new album.
- */
export const createAlbum = (albumName: string) =>
createCollection(albumName, "album");
-/**
- * Create a new quick link collection on remote, and return its local
- * representation.
- *
- * Remote only, does not modify local state.
- *
- * @param name The name to use for the new quick link collection.
- */
export const createQuickLinkCollection = (name: string) =>
createCollection(name, "album", {
subType: CollectionSubType.quicklink,
visibility: ItemVisibility.visible,
});
-/**
- * Create a new hidden album on remote, and return its local representation.
- *
- * Remote only, does not modify local state.
- *
- * @param albumName The name to use for the new hidden album.
- */
export const createHiddenAlbum = (albumName: string) =>
createCollection(albumName, "album", { visibility: ItemVisibility.hidden });
-/**
- * Create a new collection on remote, and return its local representation.
- *
- * Remote only, does not modify local state.
- *
- * @param name The name of the new collection.
- *
- * @param type The type of the new collection.
- *
- * @param magicMetadataData Optional metadata to use as the collection's private
- * mutable metadata when creating the new collection.
- */
const createCollection = async (
name: string,
type: CollectionType,
@@ -135,44 +100,26 @@ const createCollection = async (
return decryptRemoteKeyAndCollection(remoteCollection);
};
-/**
- * Given a {@link RemoteCollection}, first obtain its decryption key, and then
- * use that to decrypt and return the collection itself.
- */
const decryptRemoteKeyAndCollection = async (collection: RemoteCollection) =>
decryptRemoteCollection(collection, await decryptCollectionKey(collection));
-/**
- * Return the decrypted collection key (as a base64 string) for the given
- * {@link RemoteCollection}.
- */
export const decryptCollectionKey = async (
collection: RemoteCollection,
): Promise<string> => {
const { owner, encryptedKey, keyDecryptionNonce } = collection;
+ // Owned keys use the master key; shared keys use a sealed box.
if (owner.id == ensureLocalUser().id) {
- // The collection key of collections owned by the user is encrypted with
- // the user's master key. The nonce will be present in such cases.
return decryptBox(
{ encryptedData: encryptedKey, nonce: keyDecryptionNonce! },
await ensureMasterKeyFromSession(),
);
} else {
- // The collection key of collections shared with the user is encrypted
- // with the user's public key.
return boxSealOpen(encryptedKey, await ensureUserKeyPair());
}
};
-/**
- * Zod schema for a remote response containing a single collection.
- */
const CollectionResponse = z.object({ collection: RemoteCollection });
-/**
- * Create a collection on remote with the provided data, and return the new
- * remote collection object returned by remote on success.
- */
const postCollections = async (
collectionData: Partial<RemoteCollection>,
): Promise<RemoteCollection> => {
@@ -185,19 +132,6 @@ const postCollections = async (
return CollectionResponse.parse(await res.json()).collection;
};
-/**
- * Fetch a collection from remote by its ID.
- *
- * Remote only, does not use or modify local state.
- *
- * This is not expected to be needed in the normal flow of things, since we
- * fetch collections en masse, and efficiently, using the collection diff
- * requests.
- *
- * @param collectionID The ID of the collection to fetch.
- *
- * @returns The collection obtained from remote after decrypting its contents.
- */
export const getCollectionByID = async (
collectionID: number,
): Promise<Collection> => {
@@ -209,52 +143,16 @@ export const getCollectionByID = async (
return decryptRemoteKeyAndCollection(collection);
};
-/**
- * Zod schema for a remote response containing a an array of collections.
- */
const CollectionsResponse = z.object({
collections: z.array(RemoteCollection),
});
-/**
- * An collection upsert or deletion obtained as a result of
- * {@link getCollections} invocation.
- *
- * Each change either contains the latest data associated with the collection
- * that has been created or updated, or has a flag set to indicate that the
- * corresponding collection has been deleted.
- */
export interface CollectionChange {
- /**
- * The ID of the collection.
- */
id: number;
- /**
- * The added or updated collection, or `undefined` for deletions.
- *
- * - This will be set to the (decrypted) collection if it was added or
- * updated on remote.
- *
- * - This will not be set if the corresponding collection was deleted on
- * remote.
- */
collection?: Collection;
- /**
- * Epoch microseconds denoting when this collection was last changed
- * (created or updated or deleted).
- */
updationTime: number;
}
-/**
- * Pull the latest collections from remote.
- *
- * This function uses a delta diff, pulling only changes since the timestamp
- * saved by the last pull.
- *
- * @returns the latest list of collections, reflecting both the state in our
- * local database and on remote.
- */
export const pullCollections = async (): Promise<Collection[]> => {
const collections = await savedCollections();
let sinceTime = (await savedCollectionsUpdationTime()) ?? 0;
@@ -269,7 +167,6 @@ export const pullCollections = async (): Promise<Collection[]> => {
if (collection) {
collectionsByID.set(id, collection);
} else {
- // Collection was deleted on remote.
await removeCollectionIDLastSyncTime(id);
collectionsByID.delete(id);
}
@@ -283,18 +180,6 @@ export const pullCollections = async (): Promise<Collection[]> => {
return updatedCollections;
};
-/**
- * Fetch all collections that have been added or updated on remote since
- * {@link sinceTime}, with markers for those that have been deleted.
- *
- * @param sinceTime The {@link updationTime} of the latest collection that was
- * fetched in a previous set of changes. This allows us to resume fetching from
- * that point. Pass 0 to fetch from the beginning.
- *
- * @returns An array of {@link CollectionChange}s. It is guaranteed that there
- * will be at most one entry for a given collection in the result array. See:
- * [Note: Diff response will have at most one entry for an id]
- */
const getCollections = async (
sinceTime: number,
): Promise<CollectionChange[]> => {
@@ -314,29 +199,6 @@ const getCollections = async (
);
};
-/**
- * Fetch all files from remote and update our local database.
- *
- * Each time it updates the local database, the {@link onSetCollectionFiles}
- * callback is also invoked to give the caller a chance to bring its own
- * in-memory state up to speed.
- *
- * @param collections The user's collections. These are assumed to be the latest
- * collections on remote (that is, the pull for collections should happen prior
- * to calling this function).
- *
- * @param onSetCollectionFiles An optional callback invoked when the locally
- * saved collection files were replaced by the provided {@link collectionFiles}.
- *
- * The callback is optional because we might be called in a context where we
- * just want to update the local database, and there is no other in-memory state
- * we need to keep in sync.
- *
- * The callback can be invoked multiple times for each pull (once for each batch
- * of changes received, for each collection that was updated).
- *
- * @returns true if one or more files were updated locally, false otherwise.
- */
export const pullCollectionFiles = async (
collections: Collection[],
onSetCollectionFiles: ((files: EnteFile[]) => void) | undefined,
@@ -345,11 +207,10 @@ export const pullCollectionFiles = async (
const savedFiles = await savedCollectionFiles();
- // Prune collections files for which we no longer have a collection.
+ // Collection deletion has no file tombstone; prune by surviving IDs.
const collectionIDs = new Set(collections.map((c) => c.id));
let files = savedFiles.filter((f) => collectionIDs.has(f.collectionID));
- // Update both the saved and in-memory files to reflect the pruning.
if (files.length != savedFiles.length) {
await saveCollectionFiles(files);
onSetCollectionFiles?.(files);
@@ -359,8 +220,6 @@ export const pullCollectionFiles = async (
for (const collection of collections) {
let sinceTime = (await savedCollectionLastSyncTime(collection)) ?? 0;
if (sinceTime == collection.updationTime) {
- // The updationTime of a collection is guaranteed to be >= the
- // updationTime of any file in the collection.
continue;
}
@@ -407,32 +266,13 @@ export const pullCollectionFiles = async (
if (!hasMore) break;
}
- // There might be a difference between the latest updation time of a
- // file in the collection, and the latest time of the collection itself,
- // if something about the collection itself changed, not the files in it
- // (e.g. if the collection was renamed).
- //
- // In such cases, advance the sync time to match the collection's update
- // time so we don't do an unnecessary collection diff the next time.
+ // Collection metadata can advance without producing a file diff.
await saveCollectionLastSyncTime(collection, collection.updationTime);
}
return didUpdateFiles;
};
-/**
- * Fetch all files in the given collection have been created or updated since
- * {@link sinceTime}.
- *
- * Remote only, does not modify local state.
- *
- * @param collection The ID of the collection whose updates we want to fetch.
- *
- * @param sinceTime The timestamp of most recently update for the collection
- * that we have already pulled. This serves both as a pagination mechanish, and
- * a way to fetch a delta diff the next time the client needs to pull changes
- * from remote.
- */
const getCollectionDiff = async (collectionID: number, sinceTime: number) => {
const res = await fetch(
await apiURL("/collections/v2/diff", { collectionID, sinceTime }),
@@ -442,67 +282,30 @@ const getCollectionDiff = async (collectionID: number, sinceTime: number) => {
return FileDiffResponse.parse(await res.json());
};
-/**
- * Clear cached thumbnail of an existing file if the thumbnail data has changed.
- *
- * This function in expected to be called when we are processing a collection
- * diff, updating our local state to reflect files that were updated on remote.
- * This is an opportune moment to invalidate any cached thumbnails for files
- * whose thumbnail content has changed.
- *
- * An example of when such invalidation is necessary:
- *
- * 1. Take a photo on mobile, and let it sync via the mobile app to us (web).
- * 2. Edit the photo outside of Ente (e.g. using Apple Photos).
- * 3. When the Ente mobile client next comes into foreground, it'll update the
- * remote thumbnail for the existing file to reflect the changes.
- *
- * @param existingFile The {@link EnteFile} we had in our local database before
- * processing the diff response. Pass `undefined` to indicate that there was no
- * existing file corresponding to {@link updatedFile}; in such a case this
- * function is a no-op.
- *
- * @param updatedFile The update {@link EntneFile} (with the same file ID as the
- * {@link existingFile}) which we got in the diff response.
- */
const clearCachedThumbnailIfContentChanged = async (
existingFile: EnteFile | undefined,
updatedFile: EnteFile,
) => {
if (!existingFile) return;
- // The hashes of the files differ, which indicates that the change was in
- // the file's contents, not the metadata itself, and thus we should refresh
- // the thumbnail.
+ // Content changes invalidate thumbnails; metadata-only changes do not.
if (
metadataHash(existingFile.metadata) !=
metadataHash(updatedFile.metadata)
) {
- // This is an infrequent occurrence, so we lazily get the cache.
const thumbnailCache = await blobCache("thumbs");
await thumbnailCache.delete(updatedFile.id.toString());
}
};
-/**
- * Return all collections (both normal and hidden) that are present in our
- * local database.
- */
export const savedAllCollections = (): Promise<Collection[]> =>
savedCollections();
-/**
- * Return all normal (non-hidden) collections that are present in our local
- * database.
- */
export const savedNormalCollections = (): Promise<Collection[]> =>
savedCollections().then(
(cs) => splitByPredicate(cs, isHiddenCollection)[1],
);
-/**
- * Return all hidden collections that are present in our local database.
- */
export const savedHiddenCollections = (
currentUserID?: number,
): Promise<Collection[]> =>
@@ -513,41 +316,17 @@ export const savedHiddenCollections = (
)[0],
);
-/**
- * Return a map of the (user-facing) collection name, indexed by collection ID.
- */
export const createCollectionNameByID = (collections: Collection[]) =>
new Map(collections.map((c) => [c.id, collectionUserFacingName(c)]));
-/**
- * Return the "user facing" name of the given collection.
- *
- * Usually this is the same as the collection name, but it might be a different
- * string for special collections like default hidden collections.
- */
export const collectionUserFacingName = (collection: Collection) =>
isDefaultHiddenCollection(collection)
? defaultHiddenCollectionUserFacingName
: collection.name;
-/**
- * A CollectionFileItem represents a file in a API request to add, move or
- * restore files to a particular collection.
- */
interface CollectionFileItem {
- /**
- * The file's ID.
- */
id: number;
- /**
- * The file's key (as a base64 string), encrypted with the key of the
- * collection to which it is being added or moved.
- */
encryptedKey: string;
- /**
- * The nonce (as a base64 string) that was used during the encryption of
- * {@link encryptedKey}.
- */
keyDecryptionNonce: string;
}
@@ -555,50 +334,20 @@ const CopyFilesResponse = z.object({
oldToNewFileIDMap: z.record(z.string(), z.number()),
});
-/**
- *
- * @param collection
- * @returns the current role of the user in the collection.
- * if the currentUser is the owner then OWNER, else if
- * it was shared then checks the sharees list to find the role
- * which could be either VIEWER or COLLABORATOR.
- */
const currentUserRoleInCollection = (collection: Collection) => {
const userID = ensureLocalUser().id;
if (collection.owner.id == userID) return "OWNER";
return collection.sharees.find((sharee) => sharee.id == userID)?.role;
};
-/**
- *
- * @param collection
- * @returns true if the user can add files to a collection,
- * only the OWNER, ADMIN and COLLABORATOR can actually add
- * file to a collection.
- */
export const canAddFilesToCollection = (collection: Collection) => {
const role = currentUserRoleInCollection(collection);
return role == "OWNER" || role == "ADMIN" || role == "COLLABORATOR";
};
-/**
- *
- * @param collection
- * @returns whether the current user can directly
- * upload to the collection.
- *
- * A user can directly upload to a collection if he/she
- * is the owner of that particular collection.
- */
export const canDirectlyUploadToCollection = (collection: Collection) =>
collection.owner.id == ensureLocalUser().id;
-/**
- * Make a remote request to add the given {@link files} to the given
- * {@link collection}.
- *
- * Remote only, does not modify local state.
- */
export const addToCollection = async (
collection: Collection,
files: EnteFile[],
@@ -620,12 +369,6 @@ export const addToCollection = async (
);
});
-/**
- * Make a remote request to restore the given {@link files} to the given
- * {@link collection}.
- *
- * Remote only, does not modify local state.
- */
export const restoreToCollection = async (
collection: Collection,
files: EnteFile[],
@@ -647,16 +390,6 @@ export const restoreToCollection = async (
);
});
-/**
- * Make a remote request to move the given {@link files} (which may be in
- * different collections) to the given {@link collection}.
- *
- * This is a higher level primitive than {@link moveFromCollection} that first
- * segregates the files into per-collection sets, and then performs
- * {@link moveFromCollection} for each such set.
- *
- * Remote only, does not modify local state.
- */
export const moveToCollection = async (
collection: Collection,
files: EnteFile[],
@@ -668,13 +401,6 @@ export const moveToCollection = async (
.map(([cid, cf]) => moveFromCollection(cid, collection, cf)),
);
-/**
- * Make a remote request to move the given {@link files} from a collection (as
- * identified by its {@link fromCollectionID}) to the given
- * {@link toCollection}.
- *
- * Remote only, does not modify local state.
- */
export const moveFromCollection = async (
fromCollectionID: number,
toCollection: Collection,
@@ -697,15 +423,6 @@ export const moveFromCollection = async (
}),
);
});
-/**
- *
- * @param files
- * @returns list of unique files from the files argument.
- *
- * This function just iterates through the files and then
- * stores the file.id and skips any files for which the
- * file.id has been already been seen to prevent duplicates.
- */
const uniqueFilesByID = (files: EnteFile[]) => {
const seen = new Set<number>();
const uniqueFiles: EnteFile[] = [];
@@ -719,14 +436,6 @@ const uniqueFilesByID = (files: EnteFile[]) => {
return uniqueFiles;
};
-/**
- *
- * @param collectionID
- * @param collectionFiles
- * @returns Filters the collectionFiles and create a
- * new set with the fileIds of files which belong
- * to the collection having it's id collectionID.
- */
const fileIDsInCollection = (
collectionID: number,
collectionFiles: EnteFile[],
@@ -737,30 +446,12 @@ const fileIDsInCollection = (
.map((file) => file.id),
);
-/**
- *
- * @param file
- * @returns A composite key of the form `${metadataHash}:${fileType}`, used to
- * detect content-equivalent files. Returns undefined if the file has no
- * metadata hash.
- */
const hashAndTypeKey = (file: EnteFile) => {
const hash = metadataHash(file.metadata);
if (!hash) return undefined;
return `${hash}:${file.metadata.fileType}`;
};
-/**
- *
- * @param files
- * @param currentUserID
- * @returns A Mapping which has a unique ${hash}:${file.metadata.fileType} key
- * for each of the file which is owned by the current user.
- *
- * This map is currently used in flows where the current user performs actions
- * on shared-files/shared albums, where we check if the current user by any chance
- * have a copy of the files on which the action is being performed on.
- */
const userOwnedEquivalentFilesByHashAndType = (
files: EnteFile[],
currentUserID: number,
@@ -778,48 +469,21 @@ const userOwnedEquivalentFilesByHashAndType = (
return equivalents;
};
-// Bridges shared favorite toggles before the remote add/move has been pulled
-// into local DB.
+// Bridge repeated shared favorite toggles before the next pull.
const pendingFavoriteFilesByHashAndType = new Map<string, EnteFile>();
let pendingUserFavoritesCollection: Collection | undefined;
let pendingUserFavoritesCollectionPromise: Promise<Collection> | undefined;
-/**
- *
- * @param sourceFiles The files the user originally performed the actions on. It could be owned/non-owned files.
- *
- * @param favoriteFiles The actual files that were added/removed from the favorites. For shared files
- * this maybe a different user-owned equivalent file.
- *
- * @param userID The userId of the current loggedIn user.
- *
- * If the user favorites a shared file X, the actual Favorites entry may be user-owned file Y.
- * Before remote pull updates local DB, the UI may still only know about shared file X. This
- * helper remembers:
- *
- * X hash:type -> Y
- *
- * Then if the user immediately unfavorites or favorites again, the code can resolve the real
- * favorite file Y instead of trying to operate on shared file X.
- *
- * This also records owned source files, so an owned favorite can immediately
- * resolve shared hash-equivalent rows before the remote pull updates local DB.
- *
- */
const rememberPendingFavoriteFiles = (
sourceFiles: EnteFile[],
favoriteFiles: EnteFile[],
userID: number,
) => {
- // Creating a map by hashAndType for the files which where favorited now
const favoriteFilesByHashAndType = userOwnedEquivalentFilesByHashAndType(
favoriteFiles,
userID,
);
- // Iterating through the sourceFiles to check whether the files which where
- // favorited have a hashAndType match in favoriteFilesByHashAndType
- // if so storing the file in the pendingFavoriteFilesByHashAndType
for (const sourceFile of sourceFiles) {
const hashAndType = hashAndTypeKey(sourceFile);
const favoriteFile = hashAndType
@@ -831,35 +495,12 @@ const rememberPendingFavoriteFiles = (
}
};
-/**
- *
- * @param files The files which are to be favorited/un-favorited
- * @param userID The userId of the current loggedIn user.
- * @returns
- *
- * remainingFiles: The files which doesn't have an user-owned copy yet and therefore considered
- * as a shared-file/non-owned file
- *
- * pendingFiles: The files which already have an owned copy. It could the file was
- * already owned by the user or because of a prior favoriting the file now has a owned copy.
- */
const splitPendingFavoriteFiles = (files: EnteFile[], userID: number) => {
const pendingFiles: EnteFile[] = [];
- // Files for which the current user is the owner.
const remainingFiles: EnteFile[] = [];
const seenPendingFileIDs = new Set<number>();
- /**
- * Iterating through the files and then pushing the file to the remainingFiles array
- * if it's an owned file or if it's a shared file without an remembered user-owned equivalent
- *
- * For non-owned/shared files, getting the metadataKey of the file and checking
- * if the pendingFavoriteFilesByHashAndType has it, if so it means the file already
- * has a owned copy, like it was favorited before and the remote pull is yet to happen.
- *
- * If so then pushing the file to the pendingFiles else pushing it to the remainingFiles.
- */
for (const file of files) {
if (file.ownerID == userID) {
remainingFiles.push(file);
@@ -884,15 +525,6 @@ const splitPendingFavoriteFiles = (files: EnteFile[], userID: number) => {
return { pendingFiles, remainingFiles };
};
-/**
- *
- * @param fileIDs
- * @returns
- *
- * We had introduced a variable to store the files which
- * where just favorited, so that they aren't copied again
- * as the remotePull doesn't occur after the favoriting action.
- */
const forgetPendingFavoriteFileIDs = (fileIDs: number[]) => {
if (!fileIDs.length) return;
@@ -907,50 +539,25 @@ const forgetPendingFavoriteFileIDs = (fileIDs: number[]) => {
}
};
-/**
- *
- * @param dstCollection
- * @param files
- * @returns a new List with each file having their id, ownerID and collectionId
- * updated. the fileId points to the id of the newly created file,
- * the ownerId points to the id of the currentUser and collectionId points to the
- * dstCollection.id
- */
export const copyFiles = async (
dstCollection: Collection,
files: EnteFile[],
): Promise<EnteFile[]> => {
if (!files.length) return [];
- /**
- * Getting the currentUserId and then ensuring that the
- * dstCollection is indeed owned by that person. We only support
- * uploading to owned collection so hence this verification.
- */
+ // Copying creates owned IDs, so the destination must be owned.
const currentUserID = ensureLocalUser().id;
if (dstCollection.owner.id != currentUserID) {
throw new Error("Destination collection must be owned by the actor");
}
- // Filtering out any duplicates from the list of files to be copied
const uniqueFiles = uniqueFilesByID(files);
const copiedFiles: EnteFile[] = [];
- /**
- * Callers are expected to pass only files which aren't owned by the
- * currentUser (the batch validation below enforces this). Since these files
- * are already uploaded to Ente, they will belong to some source collection,
- * so we group them by their source collectionID and iterate per-group.
- */
for (const [srcCollectionID, sourceFiles] of groupFilesByCollectionID(
uniqueFiles,
).entries()) {
for (const batchFiles of batch(sourceFiles, copyRequestBatchSize)) {
- /**
- * As said earlier this is strictly for files which aren't owned
- * by the currentUser and only such files can be copied so thus
- * doing a final validation.
- */
if (
batchFiles.some(
(file) =>
@@ -963,7 +570,6 @@ export const copyFiles = async (
);
}
- // Encrypting the files with the dstCollection Key
const encryptedFileKeys = await encryptWithCollectionKey(
dstCollection,
batchFiles,
@@ -980,21 +586,16 @@ export const copyFiles = async (
});
ensureOk(res);
- // This is just the server responding back with,
- // the old file with ID X is now a new file with ID Y.
const { oldToNewFileIDMap } = CopyFilesResponse.parse(
await res.json(),
);
- // Iterating through files and checking if they exist
- // in the mapping, which indicates the file was copied successfully.
for (const file of batchFiles) {
const copiedFileID = oldToNewFileIDMap[file.id.toString()];
if (!copiedFileID) {
throw new Error(`Failed to copy file ${file.id}`);
}
- // If success then updating the copiedFiles array.
copiedFiles.push({
...file,
id: copiedFileID,
@@ -1008,50 +609,15 @@ export const copyFiles = async (
return copiedFiles;
};
-/**
- * This function is currenly used in the upload to shared album flow.
- * For uploading a file to a shared-album for which the currentUser
- * doesn't have an equivalent copy, the file first has to be uploaded to the
- * user's uncategorized so the user now owns a copy of the file.
- *
- * @returns the uncategorized album of the currentUser.
- */
const savedUserUncategorizedCollection = async () => {
const userID = ensureLocalUser().id;
return findUserUncategorizedCollection(await savedCollections(), userID);
};
-/**
- *
- * Checking whether the currentUser already has a uncategorized Collection,
- * if so then returning the reference to that else creating the same
- * and then returning the instance of the newly created collection.
- *
- * @returns the uncategorized collection of the currentUser if it already
- * exists, otherwise the newly created uncategorized collection.
- */
export const savedOrCreateUserUncategorizedCollection = async () =>
(await savedUserUncategorizedCollection()) ??
createUncategorizedCollection();
-/**
- *
- * @param dstCollection
- * @param files
- *
- * This function classified the files which are to be added to the
- * dstCollection based on the ownership of each of the files.
- *
- * The filesToAdd() list is for files in otherOwnedFiles whose content can be
- * represented by an equivalent file already owned by the current user. If the
- * code finds a user-owned equivalent with the same metadata hash and file type,
- * it reuses that file and links it to the dstCollection.
- *
- * The filesToCopy() are for files owned by someone else for which
- * the current user has no equivalent copy. Those cannot be directly reused.
- * So a copy of them is created for the current user and then linked
- * with the dstCollection.
- */
export const addOrCopyToCollection = async (
dstCollection: Collection,
files: EnteFile[],
@@ -1059,110 +625,55 @@ export const addOrCopyToCollection = async (
const addedFiles: EnteFile[] = [];
if (!files.length) return addedFiles;
- /**
- * The user who is adding the files to the dstCollection must be
- * either the OWNER, ADMIN or atleast a COLLABORATOR to add the file
- * to the album.
- *
- * Therefore checking before proceeding and if not then throwing error.
- */
if (!canAddFilesToCollection(dstCollection)) {
throw new Error("Current user cannot add files to this collection");
}
- // Getting the ID of the currently logged-in user, collection files.
const currentUserID = ensureLocalUser().id;
const collectionFiles = await savedCollectionFiles();
- /**
- * Now since we have the files across all the collections and the
- * id of the collection to which we want to upload the files to
- *
- * Getting the file IDs which are already present in the dstCollection
- */
const destinationFileIDs = fileIDsInCollection(
dstCollection.id,
collectionFiles,
);
- /**
- * Getting the list of the files which aren't actually already present
- * in the destination. We don't want to upload files which already exist
- * in the destination therefore this check.
- *
- * Here files indiciate the files which the user wants to add to the album
- */
const filesMissingFromDestination = uniqueFilesByID(files).filter(
(file) => !destinationFileIDs.has(file.id),
);
- // If all the files, already exists then,
- // we have nothing pending so returning.
if (!filesMissingFromDestination.length) return addedFiles;
- /**
- * Files which are owned by the current user and not owned
- * both have different upload process therefore this filtering.
- */
const [ownedFiles, otherOwnedFiles] = splitByPredicate(
filesMissingFromDestination,
(file) => file.ownerID == currentUserID,
);
- /**
- * For files already owned by the current user, we only link existing files
- * to the destination collection. No content upload, no new file IDs, and no
- * removal from current collections—just membership entries on the server.
- *
- * It's a far more straightforward process compared to the upload of
- * non-owned files.
- */
if (ownedFiles.length) {
await addToCollection(dstCollection, ownedFiles);
ownedFiles.forEach((file) => destinationFileIDs.add(file.id));
addedFiles.push(...ownedFiles);
}
- // If there are no files which are owned but by others
- // then skipping the rest of the process.
if (!otherOwnedFiles.length) return addedFiles;
- /**
- * Say if user A uploaded a file X to a shared album and you
- * also have a copy of the same file let it be Y. Then when you try to
- * add the file X to a shared album instead of X it's Y being added.
- *
- * It's done by checking the metadatahash and fileType to see if the
- * user who is initating the action has a copy of the same file.
- */
+ // Reuse an owned hash/type equivalent; copy only when none exists.
const userOwnedFilesByHashAndType = userOwnedEquivalentFilesByHashAndType(
collectionFiles,
currentUserID,
);
- // Storing the user owned files which can be directly added
const filesToAdd: EnteFile[] = [];
- // Storing other owned-files without an user-owned equivalent
const filesToCopy: EnteFile[] = [];
- /**
- * Both the below Set(s) are for preventing duplication. Assume there are
- * two shared files X1 and X2 and then if both of them match the same owned
- * file Y then we need to prevent Y from being pushed to filesToAdd twice.
- * similarly for the filesToCopy as well
- */
const seenAddFileIDs = new Set<number>();
const seenCopyFileIDs = new Set<number>();
for (const file of otherOwnedFiles) {
const fileHashAndTypeKey = hashAndTypeKey(file);
- // Checking if the user has a file with matching hash
const userOwnedEquivalent = fileHashAndTypeKey
? userOwnedFilesByHashAndType.get(fileHashAndTypeKey)
: undefined;
const shouldAddOwnedEquivalent = !!userOwnedEquivalent;
- // If the file needs to be added or copied then pushing
- // the file ID into corresponding variables.
if (shouldAddOwnedEquivalent) {
if (!seenAddFileIDs.has(userOwnedEquivalent.id)) {
seenAddFileIDs.add(userOwnedEquivalent.id);
@@ -1174,23 +685,10 @@ export const addOrCopyToCollection = async (
}
}
- /**
- * If you are wondering why we need this check again because we did it
- * once at the filesMissingFromDestination. the filesToAdd might have
- * different or new IDs which weren't there in the files earlier.
- *
- * For otherOwnedFiles, the code may replace thesource file X
- * with a different user owned equivalent Y.
- */
const reusableOwnedFiles = uniqueFilesByID(filesToAdd).filter(
(file) => !destinationFileIDs.has(file.id),
);
- /**
- * Adding the files to the dstCollection.
- * fyi: these are the files for which the currentUser
- * had a equivalent copy with a matching metadata + fileType.
- */
if (reusableOwnedFiles.length) {
await addToCollection(dstCollection, reusableOwnedFiles);
reusableOwnedFiles.forEach((file) => destinationFileIDs.add(file.id));
@@ -1199,28 +697,14 @@ export const addOrCopyToCollection = async (
if (!filesToCopy.length) return addedFiles;
- /**
- * To directly upload to a collection, the currentUser must be the
- * the owner of the same, checking that and if not then,
- */
+ // A shared destination cannot own the copy; stage it in Uncategorized.
const copyDestination = canDirectlyUploadToCollection(dstCollection)
? dstCollection
: await savedOrCreateUserUncategorizedCollection();
- /**
- * If the user owns the dstCollection then copyDestination will have reference
- * of that collection in it else, it will be having the reference for the uncategorized
- * collection to which the files is copied to.
- */
const copiedFiles = await copyFiles(copyDestination, filesToCopy);
if (copyDestination.id != dstCollection.id) {
- /**
- * The copiedFiles variable have the reference of the files which are
- * uploaded to the uncatgroized and now these files have a proper EnteFile
- * schema, therefore now we can add these files to the dstCollection after checking
- * the fileIds doesn't already exist there.
- */
const filesToAddAfterCopy = uniqueFilesByID(copiedFiles).filter(
(file) => !destinationFileIDs.has(file.id),
);
@@ -1238,11 +722,6 @@ export const addOrCopyToCollection = async (
return addedFiles;
};
-/**
- * Return an array of {@link CollectionFileItem}s, one for each file in
- * {@link files}, containing the corresponding file' ID and keys, but this time
- * encrypted using the key of the given {@link collection}.
- */
const encryptWithCollectionKey = async (
collection: Collection,
files: EnteFile[],
@@ -1258,15 +737,6 @@ const encryptWithCollectionKey = async (
}),
);
-/**
- * Make a remote request to move the given {@link files} to trash.
- *
- * @param files The {@link EnteFile}s to move to trash. The API request needs
- * both a file ID and a collection ID, but there should be at most one entry for
- * a particular fileID in this array.
- *
- * Remote only, does not modify local state.
- */
export const moveToTrash = async (files: EnteFile[]) => {
await batched(files, async (batchFiles) =>
ensureOk(
@@ -1285,11 +755,6 @@ export const moveToTrash = async (files: EnteFile[]) => {
forgetPendingFavoriteFileIDs(files.map((file) => file.id));
};
-/**
- * Make a remote request to delete the given {@link fileIDs} from trash.
- *
- * Remote only, does not modify local state.
- */
export const deleteFromTrash = async (fileIDs: number[]) => {
await batched(fileIDs, async (batchIDs) =>
ensureOk(
@@ -1303,83 +768,8 @@ export const deleteFromTrash = async (fileIDs: number[]) => {
forgetPendingFavoriteFileIDs(fileIDs);
};
-/**
- * Remove the given files from the specified collection owned by the user.
- *
- * Reads local state but does not modify it. The effects are on remote.
- *
- * @param collection A collection (either owned by the user, or shared with the
- * user).
- *
- * @param files The files to remove from the collection. The files owned by the
- * user will be removed. If the collection is not owned by the user, then any
- * files that are not owned by the user will not be processed (unless the user
- * is an admin of the collection). In such cases, this function will return a
- * count less than the count of the provided files (after having removed what
- * can be removed).
- *
- * @returns The count of files that were processed. This can be less than the
- * count of the provided {@link files} if some files were not processed because
- * because they belong to other users (and {@link collection} also does not
- * belong to the current user, and the user is not an admin).
- *
- * [Note: Removing files from a collection]
- *
- * There are four scenarios
- *
- * own file shared file
- * own collection M R
- * admin in collection R R
- * others collection R not supported
- *
- * M (move) when both collection and file belongs to user
- * R (remove) when only one of them belongs to the user, or user is admin
- *
- * The move operation is not supported across ownership boundaries. The remove
- * operation is only supported across ownership boundaries, but the user should
- * have ownership of either the file or collection (not both), or be an admin.
- *
- * In more detail, the above scenarios can be described this way.
- *
- * 1. Move: If the user owns both the collection and the file they're trying to
- * remove from the collection, then instead of a remove the client needs to
- * move it to a different user owned collection in which it already exists
- * (such a move acts as a remove). If it doesn't exist in any other user
- * owned collection, then move it to the user's "Uncategorized" collection.
- * The intent is that a "remove from collection" should not remove the last
- * copy of a file (thus deleting it).
- *
- * 2. Remove: If the user does not own the file being removed, or owns the file
- * being removed but does not own the collection from which it is being
- * removed, they can remove it from the collection using the POST
- * "/collections/v3/remove-files".
- *
- * 3. Admin remove: If the user is an admin of a collection they don't own, they
- * can remove any file from the collection (including files they don't own).
- *
- * 4. Not supported: Removing a file the user does not own from a collection
- * that the user does not own and is not an admin of.
- *
- * The "remove from collection" primitive is provided to the user both as a UI
- * action (on selecting files in a collection), and as an implicit action if the
- * user chooses the option to "keep files" when deleting a collection.
- *
- * This entire shebang is implemented by the following set of functions:
- *
- * 1. [Public] {@link removeFromCollection} - Handles both own and others
- * collections by delegating to the one of the following functions.
- *
- * 2. [Public] {@link removeFromOwnCollection} - Handles both cases for own
- * collections by delegating to either "Move" or "Remove"
- *
- * 3. [Private] {@link removeFromOthersCollection} - Handles cases for other's
- * collections. If the user is an admin, they can remove all files. Otherwise
- * only the user's own files can be removed.
- *
- * 4. [Private] {@link removeOwnFilesFromOwnCollection} implements the "Move".
- *
- * 5. [Private] {@link removeNonCollectionOwnerFiles} implements the "Remove".
- */
+// The remove endpoint crosses ownership boundaries.
+// Owned files leave owned collections by moving, so one copy survives.
export const removeFromCollection = async (
collection: Collection,
files: EnteFile[],
@@ -1411,19 +801,16 @@ const removeFromOthersCollection = async (
files: EnteFile[],
) => {
const userID = ensureLocalUser().id;
- // Check if user is an admin of this collection
const isAdmin =
collection.sharees.find((s) => s.id == userID)?.role == "ADMIN";
if (isAdmin) {
- // Admins can remove all files from the collection
if (files.length) {
await removeNonCollectionOwnerFiles(collection.id, files);
}
return files.length;
}
- // Non-admins can only remove their own files
const [userFiles] = splitByPredicate(files, (f) => f.ownerID == userID);
if (userFiles.length) {
await removeNonCollectionOwnerFiles(collection.id, userFiles);
@@ -1431,16 +818,7 @@ const removeFromOthersCollection = async (
return userFiles.length;
};
-/**
- * Remove the given user owned files from the given collection also owned by the
- * user, ensuring that at least one user owned instance is retained for them
- * (either in a different user owned collection in which they already existed,
- * or in the user's "Uncategorized" collection as a fallback).
- *
- * Reads local state but does not modify it. The effects are on remote.
- *
- * This is used as a subroutine of [Note: Removing files from a collection].
- */
+// Preserve one owned instance, falling back to Uncategorized.
const removeOwnFilesFromOwnCollection = async (
collectionID: number,
filesToRemove: EnteFile[],
@@ -1451,42 +829,31 @@ const removeOwnFilesFromOwnCollection = async (
const collectionsByID = new Map(collections.map((c) => [c.id, c]));
- // This set keeps a running track of file IDs that still need to be removed.
- // It is seeded with the original set of files we were asked to remove.
const filesToRemoveIDs = new Set(filesToRemove.map((f) => f.id));
- // A predicate that checks if the given file is still pending removal.
const pendingRemove = (f: EnteFile) => filesToRemoveIDs.has(f.id);
const collectionFilesToRemove = collectionFiles.filter(pendingRemove);
const groups = groupFilesByCollectionID(collectionFilesToRemove);
for (const [targetCollectionID, filesInCollection] of groups.entries()) {
- // Ignore the source collection itself.
if (targetCollectionID == collectionID) continue;
const targetCollection = collectionsByID.get(targetCollectionID)!;
- // We want a copy to exist in at least one other user owned collection.
if (targetCollection.owner.id != userID) continue;
- // We'll move to uncategorized after the loop (if they still remain).
if (targetCollection.type == "uncategorized") continue;
const filesInCollectionToRemove =
filesInCollection.filter(pendingRemove);
if (!filesInCollectionToRemove.length) continue;
- // The file already exists in the target collection, but this acts as
- // "remove" from the source.
await moveFromCollection(
collectionID,
targetCollection,
filesInCollectionToRemove,
);
- // Mark the files we just moved as been taken care of.
filesInCollectionToRemove.forEach((f) => filesToRemoveIDs.delete(f.id));
}
- // Any files that were not moved so far, move them to uncategorized,
- // creating uncategorized if needed.
const remainingFiles = filesToRemove.filter(pendingRemove);
if (remainingFiles.length) {
const uncategorizedCollection =
@@ -1501,31 +868,6 @@ const removeOwnFilesFromOwnCollection = async (
}
};
-/**
- * Remove the provided files from the provided collection on remote.
- *
- * Only files which do not belong to the collection owner can be removed from
- * the collection using this endpoint. That is,
- *
- * - Either the user owns the collection and the all files being removed are
- * owned by somebody else, or
- *
- * - The user owns all the files being removed, but the collection belongs to
- * somebody else.
- *
- * If the collection owner wants to remove files owned by them, then their
- * client should first move those files first to other collections owned by the
- * collection owner.
- *
- * Remote only, does not modify local state.
- *
- * See also: [Note: Removing files from a collection].
- *
- * @param collectionID The ID of collection from which to remove the files.
- *
- * @param files A list of files which do not belong to the user, and which we
- * the user wants to remove from the given collection.
- */
const removeNonCollectionOwnerFiles = async (
collectionID: number,
files: EnteFile[],
@@ -1543,20 +885,6 @@ const removeNonCollectionOwnerFiles = async (
),
);
-/**
- * Delete a collection on remote.
- *
- * Reads local state but does not modify it. The effects are on remote.
- *
- * @param collectionID The ID of the collection to delete.
- *
- * @param opts Deletion options. In particular, if {@link keepFiles} is true,
- * then the any of the user's files that only exist in this collection are
- * first moved to another one of the user's collection (or Uncategorized if no
- * such collection exists) before deleting the collection.
- *
- * See: [Note: Removing files from a collection]
- */
export const deleteCollection = async (
collectionID: number,
opts?: { keepFiles?: boolean },
@@ -1582,21 +910,12 @@ export const deleteCollection = async (
);
};
-/**
- * Rename a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * @param collection The collection to rename.
- *
- * @param newName The new name of the collection
- */
export const renameCollection = async (
collection: Collection,
newName: string,
) => {
+ // Named quick links become regular collections.
if (collection.magicMetadata?.data.subType == CollectionSubType.quicklink) {
- // Convert quicklinks to a regular collection before giving them a name.
await updateCollectionPrivateMagicMetadata(collection, {
subType: CollectionSubType.default,
});
@@ -1625,18 +944,6 @@ const postCollectionsRename = async (renameRequest: RenameRequest) =>
}),
);
-/**
- * Change the visibility (normal, archived, hidden) of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This function works with both collections owned by the user, and collections
- * shared with the user.
- *
- * @param collection The collection whose visibility we want to change.
- *
- * @param visibility The new visibility (normal, archived, hidden).
- */
export const updateCollectionVisibility = async (
collection: Collection,
visibility: ItemVisibility,
@@ -1645,106 +952,32 @@ export const updateCollectionVisibility = async (
? updateCollectionPrivateMagicMetadata(collection, { visibility })
: updateCollectionShareeMagicMetadata(collection, { visibility });
-/**
- * Change the pinned state of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This function works only for collections owned by the user.
- *
- * @param collection The collection whose order we want to change.
- *
- * @param order Whether on not the collection is pinned.
- */
export const updateCollectionOrder = async (
collection: Collection,
order: CollectionOrder,
) => updateCollectionPrivateMagicMetadata(collection, { order });
-/**
- * Change the order (pin/unpin) of a shared collection on remote for the sharee.
- *
- * Remote only, does not modify local state.
- *
- * This function works only for collections shared with the user (not owned).
- *
- * @param collection The shared collection whose order we want to change.
- *
- * @param order Whether on not the collection is pinned by the sharee.
- */
export const updateShareeCollectionOrder = async (
collection: Collection,
order: CollectionOrder,
) => updateCollectionShareeMagicMetadata(collection, { order });
-/**
- * Change the sort order of the files with a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This function works only for collections owned by the user.
- *
- * @param collection The collection whose file sort order we want to change.
- *
- * @param asc If true, then the files are sorted ascending (oldest first).
- * Otherwise they are sorted descending (newest first).
- */
export const updateCollectionSortOrder = async (
collection: Collection,
asc: boolean,
) => updateCollectionPublicMagicMetadata(collection, { asc });
-/**
- * Change the cover photo of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This function works only for collections owned by the user.
- *
- * @param collection The collection whose cover we want to change.
- *
- * @param coverID The file ID to set as the cover.
- *
- * Pass `0` to reset to the default cover.
- */
export const updateCollectionCover = async (
collection: Collection,
coverID: number,
) => updateCollectionPublicMagicMetadata(collection, { coverID });
-/**
- * Change the layout type of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This function works only for collections owned by the user.
- *
- * @param collection The collection whose layout we want to change.
- *
- * @param layout The layout type ("masonry", "grouped", "continuous", "trip").
- */
export const updateCollectionLayout = async (
collection: Collection,
layout: string,
) => updateCollectionPublicMagicMetadata(collection, { layout });
-/**
- * Update the private magic metadata of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * @param collection The collection whose magic metadata we want to update.
- *
- * The existing magic metadata of this collection is used both to obtain the
- * current magic metadata version, and the existing contents on top of which the
- * updates are applied, so it is imperative that both these values are up to
- * sync with remote otherwise the update will fail.
- *
- * @param updates A non-empty subset of
- * {@link CollectionPrivateMagicMetadataData} entries.
- *
- * See: [Note: Magic metadata data cannot have nullish values]
- */
+// Every metadata merge below requires current remote data and version.
const updateCollectionPrivateMagicMetadata = async (
{ id, key, magicMetadata }: Collection,
updates: CollectionPrivateMagicMetadataData,
@@ -1760,9 +993,6 @@ const updateCollectionPrivateMagicMetadata = async (
),
});
-/**
- * Update the private magic metadata of a single collection on remote.
- */
const putCollectionsMagicMetadata = async (
updateRequest: UpdateMagicMetadataRequest,
) =>
@@ -1774,14 +1004,6 @@ const putCollectionsMagicMetadata = async (
}),
);
-/**
- * Update the public magic metadata of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This is a variant of {@link updateCollectionPrivateMagicMetadata} that works
- * with the {@link pubMagicMetadata} of a collection.
- */
const updateCollectionPublicMagicMetadata = async (
{ id, key, pubMagicMetadata }: Collection,
updates: CollectionPublicMagicMetadataData,
@@ -1797,9 +1019,6 @@ const updateCollectionPublicMagicMetadata = async (
),
});
-/**
- * Update the public magic metadata of a single collection on remote.
- */
const putCollectionsPublicMagicMetadata = async (
updateRequest: UpdateMagicMetadataRequest,
) =>
@@ -1811,14 +1030,6 @@ const putCollectionsPublicMagicMetadata = async (
}),
);
-/**
- * Update the per-sharee magic metadata of a collection on remote.
- *
- * Remote only, does not modify local state.
- *
- * This is a variant of {@link updateCollectionPrivateMagicMetadata} that works
- * with the {@link sharedMagicMetadata} of a collection.
- */
const updateCollectionShareeMagicMetadata = async (
{ id, key, sharedMagicMetadata }: Collection,
updates: CollectionShareeMagicMetadataData,
@@ -1834,9 +1045,6 @@ const updateCollectionShareeMagicMetadata = async (
),
});
-/**
- * Update the sharee magic metadata of a single shared collection on remote.
- */
const putCollectionsShareeMagicMetadata = async (
updateRequest: UpdateMagicMetadataRequest,
) =>
@@ -1848,44 +1056,17 @@ const putCollectionsShareeMagicMetadata = async (
}),
);
-/**
- * Create a new collection of type "favorites" for the user on remote, and
- * return its local representation.
- *
- * Remote only, does not modify local state.
- *
- * Each user can have at most one collection of type "favorites" owned by them.
- * While this function does not enforce the constraint locally, it will fail
- * because remote will enforce the constraint and fail the request when we
- * attempt to create a second collection of type "favorites".
- */
const createFavoritesCollection = () =>
createCollection(favoritesCollectionName, "favorites");
-/**
- * Create a new collection of type "uncategorized" for the user on remote, and
- * return its local representation.
- *
- * Remote only, does not modify local state.
- *
- * Each user can have at most one collection of type "uncategorized" owned by
- * them. While this function does not enforce the constraint locally, it will
- * fail because remote will enforce the constraint and fail the request when we
- * attempt to create a second collection of type "uncategorized".
- */
export const createUncategorizedCollection = () =>
createCollection(uncategorizedCollectionName, "uncategorized");
-/**
- * Return the user's own favorites collection if one is found in the local
- * database. Otherwise create a new one and return that.
- *
- * Reads local state but does not modify it. The effects are on remote.
- */
const savedOrCreateUserFavoritesCollection = async () => {
const favoritesCollection = await savedUserFavoritesCollection();
if (favoritesCollection) return favoritesCollection;
+ // Avoid creating a second Favorites before the first one is pulled.
pendingUserFavoritesCollectionPromise ??= createFavoritesCollection()
.then((collection) => {
pendingUserFavoritesCollection = collection;
@@ -1898,17 +1079,12 @@ const savedOrCreateUserFavoritesCollection = async () => {
return pendingUserFavoritesCollectionPromise;
};
-/**
- * Return the user's own favorites collection if present in the local database,
- * or one created during this session before the next remote pull.
- */
export const savedUserFavoritesCollection = async () => {
const userID = ensureLocalUser().id;
const collections = await savedCollections();
return (
collections.find(
(collection) =>
- // See: [Note: User and shared favorites]
collection.type == "favorites" && collection.owner.id == userID,
) ??
(pendingUserFavoritesCollection?.owner.id == userID
@@ -1917,56 +1093,33 @@ export const savedUserFavoritesCollection = async () => {
);
};
-/**
- * Mark the provided {@link files} as the user's favorites by adding them to the
- * user's favorites collection.
- *
- * If the user doesn't yet have a favorites collection, it is created.
- *
- * Reads local state but does not modify it. The effects are on remote.
- */
export const addToFavoritesCollection = async (files: EnteFile[]) => {
const userID = ensureLocalUser().id;
- // Currenly we can only favorite shared files which have a proper metadataHash
- // therefore filtering to check if there are files without this data.
const hashlessSharedFile = files.find(
(file) => file.ownerID != userID && !hashAndTypeKey(file),
);
- // If there are files without metadata hash to be favorited, then rejecting the change
if (hashlessSharedFile) {
throw new Error("Cannot favorite shared files without metadata hash");
}
- // Getting the favorites collection of the user, if there is no favorite collection
- // for this particular user at the moment this function actaully creates one.
-
const favoritesCollection = await savedOrCreateUserFavoritesCollection();
- // Splitting the files based on their ownership.
const { pendingFiles, remainingFiles } = splitPendingFavoriteFiles(
files,
userID,
);
- // Pending files need to be just added to the favorite collection,
- // since they already have a user-owned copy so routing them that way.
if (pendingFiles.length) {
await addToCollection(favoritesCollection, pendingFiles);
}
- // Remaining files are those files which aren't owned by the current user
- // right now, therefore they have to be copied to the Favorites album instead
- // of adding. Therefore they are going to the addOrCopyToCollection.
const addedFiles = await addOrCopyToCollection(
favoritesCollection,
remainingFiles,
);
- // This function update the local variable pendingFavoriteFilesByHashAndType which maintains a map
- // of the files which were recently favorited/un-favorited to prevent
- // duplicate copying of the shared files into the user's album
rememberPendingFavoriteFiles(
files,
pendingFiles.concat(addedFiles),
@@ -1977,16 +1130,11 @@ export const addToFavoritesCollection = async (files: EnteFile[]) => {
export const removeFromFavoritesCollection = async (files: EnteFile[]) => {
const userID = ensureLocalUser().id;
- // Getting the saved Favorites collection of the user and if there is
- // no such collection existing then we throw an error.
const favoritesCollection = await savedUserFavoritesCollection();
if (!favoritesCollection) {
throw new Error("Favorites collection does not exist");
}
- // The files now might have files which are from shared-albums as well
- // Before removing them from the favorites we need to resolve to a
- // owned-equivalent of the same file.
const resolvedFiles = await resolveFavoritesFilesForRemoval(
favoritesCollection,
files,
@@ -2000,35 +1148,12 @@ export const removeFromFavoritesCollection = async (files: EnteFile[]) => {
rememberPendingFavoriteFiles(files, resolvedFiles, userID);
};
-/**
- *
- * @param favoritesCollection
- * @param files
- * @returns
- *
- *
- * If the user has marked a shared-file/non-owned file as favorite,
- * every single instance of that file with the matching metadataHash key
- * will be shown as favorite for the user
- *
- * This includes any files which are in the shared album as well.
- * Such files owner as well as the collection id will be different.
- *
- * Therefore we are looping through the files which the user wants to unfavorite
- * and then checking if there are any files like the above.
- *
- * if so then
- */
-
const resolveFavoritesFilesForRemoval = async (
favoritesCollection: Collection,
files: EnteFile[],
) => {
const userID = ensureLocalUser().id;
- // Looping through user's favorites and then creating a map with the user's
- // favorite files and their metadataHash key. This is used below to resolve
- // to the user-owned files which is to be unfavorited.
const favoriteFilesByHashAndType = userOwnedEquivalentFilesByHashAndType(
(await savedCollectionFiles()).filter(
(file) => file.collectionID == favoritesCollection.id,
@@ -2036,15 +1161,6 @@ const resolveFavoritesFilesForRemoval = async (
userID,
);
- /**
- * Iterating through the files which are to be unfavorited
- * and checking if they contain any files which belong to a
- * shared album(i.e. their owner as well as collectionId will differ)
- *
- * if so then getting the user-owned
- * equivalent of the file using it's metadataHash and favoriteFilesByHashAndType
- * mapping and then returning it.
- */
return files.map((file) => {
if (
file.ownerID != userID &&
@@ -2064,55 +1180,24 @@ const resolveFavoritesFilesForRemoval = async (
});
};
-/**
- * Return the default hidden collection for the user if one is found in the
- * local database. Otherwise create a new one and return that.
- *
- * Reads local state but does not modify it. The effects are on remote.
- */
const savedOrCreateDefaultHiddenCollection = async () =>
(await savedDefaultHiddenCollection()) ?? createDefaultHiddenCollection();
-/**
- * Return the user's default hidden collection, if any, present in the
- * local database.
- */
const savedDefaultHiddenCollection = async () =>
(await savedCollections()).find((collection) =>
isDefaultHiddenCollection(collection),
);
-/**
- * Create a new collection with hidden visibility on remote, marking it as the
- * default hidden collection, and return its local representation.
- *
- * Remote only, does not modify local state.
- *
- * See also: [Note: Multiple "default" hidden collections].
- */
const createDefaultHiddenCollection = () =>
createCollection(defaultHiddenCollectionName, "album", {
subType: CollectionSubType.defaultHidden,
visibility: ItemVisibility.hidden,
});
-/**
- * Return true if the provided collection is the default hidden collection.
- *
- * See also: [Note: Multiple "default" hidden collections].
- */
export const isDefaultHiddenCollection = (collection: Collection) =>
collection.magicMetadata?.data.subType == CollectionSubType.defaultHidden;
-/**
- * Extract the IDs of all the "default" hidden collections.
- *
- * [Note: Multiple "default" hidden collections].
- *
- * Normally, there is only expected to be one such collection. But to provide
- * clients laxity in synchronization, we don't enforce this and instead allow
- * for multiple such default hidden collections to exist.
- */
+// Concurrent clients may create more than one default-hidden collection.
export const findDefaultHiddenCollectionIDs = (collections: Collection[]) =>
new Set<number>(
collections
@@ -2120,21 +1205,11 @@ export const findDefaultHiddenCollectionIDs = (collections: Collection[]) =>
.map((collection) => collection.id),
);
-/**
- * Return `true` if the given collection is hidden.
- *
- * Hidden collections are those that have their visibility set to hidden for
- * the current user (owner or sharee).
- *
- * In one instance, the isHiddenCollection function is called outside of a window, like
- * for the people tab's review suggestions, this function was trigged from a worker.
- * In that case, since the worker has no access to the localStorage, we need to pass the currentUserID
- * explicitly.
- */
export const isHiddenCollection = (
collection: Collection,
currentUserID?: number,
) => {
+ // Workers must pass this ID because they cannot read the browser session.
const userID =
currentUserID ?? (haveWindow() ? ensureLocalUser().id : undefined);
@@ -2153,50 +1228,17 @@ export const isHiddenCollection = (
);
};
-/**
- * Return `true` if the given collection is archived.
- *
- * Archived collections are those that have their visibility set to hidden in the
- * collection's private magic metadata or per-sharee private metadata.
- */
export const isArchivedCollection = (collection: Collection) =>
collection.magicMetadata?.data.visibility == ItemVisibility.archived ||
collection.sharedMagicMetadata?.data.visibility == ItemVisibility.archived;
-/**
- * Return `true` if the current user can remove files from all participants in
- * the given collection.
- *
- * This is true if the user is either:
- * - The owner of the collection, or
- * - An admin of the collection
- *
- * This is used to determine if the user can remove files added by other users
- * from a shared collection.
- */
export const canRemoveFilesFromAllParticipants = (collection: Collection) => {
const userID = ensureLocalUser().id;
if (collection.owner.id == userID) return true;
- // Check if the user is an admin of this collection
const sharee = collection.sharees.find((s) => s.id == userID);
return sharee?.role == "ADMIN";
};
-/**
- * Hide the provided {@link files} by moving them to the default hidden
- * collection.
- *
- * If the default hidden collection does not already exist, it is created.
- *
- * Reads local state but does not modify it. The effects are on remote.
- *
- * Since now we also support upload to shared album on desktop/web, the files
- * got as params will also have shared files in them, whose collectionID
- * points to the shared album. And moving files from those collections aren't
- * possible.
- *
- * Therefore for such files are being removed instead of moving.
- */
export const hideFiles = async (files: EnteFile[]) => {
const userID = ensureLocalUser().id;
const defaultHiddenCollection =
@@ -2204,15 +1246,6 @@ export const hideFiles = async (files: EnteFile[]) => {
const collections = await savedCollections();
const collectionsByID = new Map(collections.map((c) => [c.id, c]));
- /**
- * Grouping the files based on their collectionID, so if a file exists
- * in a user-owned collection and non-user owned collection for those files
- * where will be two entries based on their collectionID
- *
- * the owned-collection file will be moved using /move-files endpoint
- * wherease the non-owned collection file will be removed from the shared collection
- * using the /
- */
for (const [collectionID, collectionFiles] of groupFilesByCollectionID(
files,
).entries()) {
@@ -2230,22 +1263,12 @@ export const hideFiles = async (files: EnteFile[]) => {
collectionFiles,
);
} else {
+ // Shared collections cannot move files across ownership.
await removeFromCollection(collection, collectionFiles);
}
}
};
-/**
- * Share the provided collection with another Ente user.
- *
- * Remote only, does not modify local state.
- *
- * @param collection The {@link Collection} to share.
- *
- * @param withUserEmail The email of the Ente user with whom to share it.
- *
- * @param role The desired role for the new participant.
- */
export const shareCollection = async (
collection: Collection,
withUserEmail: string,
@@ -2268,16 +1291,6 @@ export const shareCollection = async (
);
};
-/**
- * Stop sharing a collection on remote with the given user.
- *
- * Remote only, does not modify local state.
- *
- * @param collectionID The ID of the collection to stop sharing with the user
- * having the given {@link email}.
- *
- * @param email The email of the Ente user with whom to stop sharing.
- */
export const unshareCollection = async (collectionID: number, email: string) =>
ensureOk(
await fetch(await apiURL("/collections/unshare"), {
@@ -2287,10 +1300,6 @@ export const unshareCollection = async (collectionID: number, email: string) =>
}),
);
-/**
- * The subset of public URL attributes that can be customized by the user when
- * creating a link.
- */
export type CreatePublicURLAttributes = Pick<
Partial<PublicURL>,
| "enableCollect"
@@ -2300,16 +1309,6 @@ export type CreatePublicURLAttributes = Pick<
| "deviceLimit"
>;
-/**
- * Create a new public link for the given collection.
- *
- * Remote only, does not modify local state.
- *
- * @param collectionID The ID of the collection for which the public link should
- * be created.
- *
- * @param attributes Optional attributes to set when creating the public link.
- */
export const createPublicURL = async (
collectionID: number,
attributes?: CreatePublicURLAttributes,
@@ -2324,28 +1323,11 @@ export const createPublicURL = async (
return z.object({ result: RemotePublicURL }).parse(await res.json()).result;
};
-/**
- * The subset of public URL attributes that can be updated by the user after the
- * link has already been created.
- */
export type UpdatePublicURLAttributes = Omit<
Partial<PublicURL>,
"url" | "enablePassword"
> & { disablePassword?: boolean; passHash?: string };
-/**
- * Update the attributes of an existing public link for a shared collection.
- *
- * Remote only, does not modify local state.
- *
- * @param collectionID The ID of the collection whose public link to update.
- *
- * @param updates The public link attributes to modify. Only attributes
- * corresponding to entries with non nullish values will be updated, all the
- * other existing attributes will remain unmodified.
- *
- * @returns the updated public URL.
- */
export const updatePublicURL = async (
collectionID: number,
updates: UpdatePublicURLAttributes,
@@ -2359,11 +1341,6 @@ export const updatePublicURL = async (
return z.object({ result: RemotePublicURL }).parse(await res.json()).result;
};
-/**
- * Delete the public link for the collection with given {@link collectionID}.
- *
- * Remote only, does not modify local state.
- */
export const deleteShareURL = async (collectionID: number) =>
ensureOk(
await fetch(await apiURL(`/collections/share-url/${collectionID}`), {
@@ -2372,13 +1349,6 @@ export const deleteShareURL = async (collectionID: number) =>
}),
);
-/**
- * Leave a collection which had previously been shared with the user.
- *
- * Remote only, does not modify local state.
- *
- * @param collectionID The ID of the shared collection to leave.
- */
export const leaveSharedCollection = async (collectionID: number) =>
ensureOk(
await fetch(await apiURL(`/collections/leave/${collectionID}`), {
@@ -2387,9 +1357,6 @@ export const leaveSharedCollection = async (collectionID: number) =>
}),
);
-/**
- * Zod schema for a collection action (used for pending removal actions).
- */
const CollectionAction = z.object({
collectionID: z.number(),
fileID: z.number().nullish(),
@@ -2397,25 +1364,10 @@ const CollectionAction = z.object({
type CollectionAction = z.infer<typeof CollectionAction>;
-/**
- * Zod schema for the pending removal actions response.
- */
const PendingRemovalActionsResponse = z.object({
actions: z.array(CollectionAction).nullish(),
});
-/**
- * Fetch pending removal actions from remote.
- *
- * Remote only, does not modify local state.
- *
- * Pending removal actions indicate files that have been removed from a
- * collection by the owner or an admin, and should be moved to the user's
- * uncategorized collection if they exist locally.
- *
- * @returns A list of {@link CollectionAction} objects representing files that
- * should be moved to uncategorized.
- */
export const fetchPendingRemovalActions = async (): Promise<
CollectionAction[]
> => {
@@ -2428,20 +1380,6 @@ export const fetchPendingRemovalActions = async (): Promise<
return actions ?? [];
};
-/**
- * Process pending removal actions by moving affected files to the user's
- * uncategorized collection.
- *
- * This function fetches pending removal actions from remote, identifies which
- * files are affected, and moves them to the uncategorized collection. This
- * ensures that files removed from shared collections by owners/admins are not
- * lost but instead moved to a safe location.
- *
- * @param collections The current list of collections (used to find affected
- * files).
- *
- * Reads local state but does not modify it. The effects are on remote.
- */
export const movePendingRemovalActionsToUncategorized = async (
collections: Collection[],
) => {
@@ -2449,7 +1387,6 @@ export const movePendingRemovalActionsToUncategorized = async (
const pendingActions = await fetchPendingRemovalActions();
if (!pendingActions.length) return;
- // Group file IDs by collection ID
const collectionToFileIDs = new Map<number, Set<number>>();
for (const action of pendingActions) {
if (action.fileID == null) continue;
@@ -2466,20 +1403,15 @@ export const movePendingRemovalActionsToUncategorized = async (
if (!collectionToFileIDs.size) return;
- // Get all files from local storage
const collectionFiles = await savedCollectionFiles();
- // Group files by collection ID for efficient lookup
const filesByCollectionID = groupFilesByCollectionID(collectionFiles);
- // Create a map of collection ID to collection for quick lookup
const collectionByID = new Map(collections.map((c) => [c.id, c]));
- // Lazily initialized target collections (only created if needed)
let uncategorizedCollection: Collection | undefined;
let defaultHiddenCollection: Collection | undefined;
- // Process each collection with pending removal actions
for (const [
collectionID,
pendingFileIDs,
@@ -2492,13 +1424,12 @@ export const movePendingRemovalActionsToUncategorized = async (
if (!filesToMove.length) continue;
- // Determine target collection based on whether source is hidden
const isSourceHidden =
sourceCollection && isHiddenCollection(sourceCollection);
+ // Rescue removals without changing their hidden/visible boundary.
let targetCollection: Collection;
if (isSourceHidden) {
- // Move files from hidden collections to default hidden collection
if (!defaultHiddenCollection) {
defaultHiddenCollection =
collections.find(isDefaultHiddenCollection) ??
@@ -2506,7 +1437,6 @@ export const movePendingRemovalActionsToUncategorized = async (
}
targetCollection = defaultHiddenCollection;
} else {
- // Move files from normal collections to uncategorized
if (!uncategorizedCollection) {
uncategorizedCollection =
findUserUncategorizedCollection(collections, userID) ??
@@ -2515,24 +1445,10 @@ export const movePendingRemovalActionsToUncategorized = async (
targetCollection = uncategorizedCollection;
}
- // Move files to target collection (this also removes them from the
- // source collection, which is the primary goal here)
await moveFromCollection(collectionID, targetCollection, filesToMove);
}
};
-/**
- * Remove files from the uncategorized collection if they exist in other
- * user-owned albums.
- *
- * This is a cleanup operation that helps users remove duplicates from their
- * uncategorized collection. Files that exist both in uncategorized and in
- * other albums are moved out of uncategorized to one of those albums.
- *
- * Reads local state but does not modify it. The effects are on remote.
- *
- * @param uncategorizedCollection The user's uncategorized collection.
- */
export const cleanUncategorized = async (
uncategorizedCollection: Collection,
): Promise<number> => {
@@ -2540,15 +1456,12 @@ export const cleanUncategorized = async (
const collections = await savedCollections();
const collectionFiles = await savedCollectionFiles();
- // Get files in the uncategorized collection
const uncategorizedFiles = collectionFiles.filter(
(f) => f.collectionID == uncategorizedCollection.id,
);
if (!uncategorizedFiles.length) return 0;
- // Build a map from file ID to the collections it belongs to (excluding
- // uncategorized itself)
const fileIDToCollectionIDs = new Map<number, number[]>();
for (const file of collectionFiles) {
if (file.collectionID == uncategorizedCollection.id) continue;
@@ -2560,7 +1473,6 @@ export const cleanUncategorized = async (
}
}
- // Filter to only user-owned normal collections (not hidden, not shared)
const userOwnedCollectionIDs = new Set(
collections
.filter(
@@ -2574,11 +1486,9 @@ export const cleanUncategorized = async (
const collectionsByID = new Map(collections.map((c) => [c.id, c]));
- // Find files that exist in other user-owned collections
const filesToClean = uncategorizedFiles.filter((file) => {
const otherCollectionIDs = fileIDToCollectionIDs.get(file.id);
if (!otherCollectionIDs) return false;
- // Check if any of these collections are user-owned normal collections
return otherCollectionIDs.some((cid) =>
userOwnedCollectionIDs.has(cid),
);
@@ -2586,7 +1496,6 @@ export const cleanUncategorized = async (
if (!filesToClean.length) return 0;
- // Group files by their target collection for efficient batching
const filesByTargetCollection = new Map<number, EnteFile[]>();
for (const file of filesToClean) {
const otherCollectionIDs = fileIDToCollectionIDs.get(file.id)!;
@@ -2600,15 +1509,11 @@ export const cleanUncategorized = async (
filesByTargetCollection.set(targetCollectionID, existing);
}
- // Move files in batches per target collection
let cleanedCount = 0;
for (const [targetCollectionID, files] of filesByTargetCollection) {
const targetCollection = collectionsByID.get(targetCollectionID);
if (!targetCollection) continue;
- // Move files from uncategorized to the target collection.
- // This effectively removes them from uncategorized since they already
- // exist in the target.
await moveFromCollection(
uncategorizedCollection.id,
targetCollection,
diff --git a/web/packages/new/photos/services/file.ts b/web/packages/new/photos/services/file.ts
index ac82b9eea3..6520a4e674 100644
--- a/web/packages/new/photos/services/file.ts
+++ b/web/packages/new/photos/services/file.ts
@@ -15,56 +15,22 @@ import { batch } from "ente-utils/array";
import { savedHiddenCollections } from "./collection";
import { savedCollectionFiles } from "./photos-fdb";
-/**
- * An reasonable but otherwise arbitrary number of items (e.g. files) to include
- * in a single API request.
- *
- * Remote will reject too big payloads, and requests which affect multiple items
- * (e.g. files when moving files to a collection, changing the visibility of
- * selected files) are expected to be batched to keep each request of a
- * reasonable size. By default, we break the request into batches of 1000.
- */
+// Museum rejects oversized mutation payloads.
const requestBatchSize = 1000;
-/**
- * Perform an operation on batches, serially.
- *
- * The given {@link items} are split into batches, each of
- * {@link requestBatchSize}. The provided operation is called on all these
- * batches, one after the other. When all the operations are complete, the
- * function returns with an array of results (one from each batch promise
- * resolution).
- *
- * @param items The arbitrary items to break into {@link requestBatchSize}
- * batches.
- *
- * @param op The operation to perform on each batch.
- *
- * @returns A promise for an array of results, one from each batch operation. If
- * any operations fails, then the promise rejects with its failure reason.
- */
export const batched = async <T, U>(
items: T[],
op: (batchItems: T[]) => Promise<U>,
): Promise<U[]> => {
+ // Preserve request order and avoid multiplying server load.
const result: U[] = [];
for (const b of batch(items, requestBatchSize)) result.push(await op(b));
return result;
};
-/**
- * Return all files (from both normal and hidden collections) present in our
- * local database.
- */
export const computeAllCollectionFilesFromSaved = async () =>
savedCollectionFiles();
-/**
- * Return all normal (non-hidden) files present in our local database.
- *
- * The long name and the "compute" in it is to signal that this is not just a DB
- * read, and that it also does some potentially non-trivial computation.
- */
export const computeNormalCollectionFilesFromSaved = async (
currentUserID?: number,
) => {
@@ -81,44 +47,13 @@ export const computeNormalCollectionFilesFromSaved = async (
return collectionFiles.filter((f) => !hiddenFileIDs.has(f.id));
};
-/**
- * Change the visibility (normal, archived, hidden) of a list of files on
- * remote.
- *
- * Remote only, does not modify local state.
- *
- * The visibility of an {@link EnteFile} is stored in its private magic
- * metadata, so this function in effect updates the private magic metadata of
- * the given files on remote.
- *
- * @param files The list of files whose visibility we want to change. All the
- * files will get their visibility updated to the new, provided, value.
- *
- * @param visibility The new visibility (normal, archived, hidden).
- */
+// Mutations below are remote-only; callers must pull or overlay local state.
export const updateFilesVisibility = async (
files: EnteFile[],
visibility: ItemVisibility,
) => batched(files, (b) => updateFilesPrivateMagicMetadata(b, { visibility }));
-/**
- * Update the private magic metadata of a list of files on remote.
- *
- * Remote only, does not modify local state.
- *
- * @param file The list of files whose magic metadata we want to update. The
- * same updates will be applied to the magic metadata of all the files.
- *
- * The existing magic metadata of the provided files is used both to obtain the
- * current magic metadata version, and the existing contents on top of which the
- * updates are applied, so it is imperative that both these values are up to
- * sync with remote otherwise the update will fail.
- *
- * @param updates A non-empty subset of {@link FilePrivateMagicMetadataData}
- * entries.
- *
- * See: [Note: Magic metadata data cannot have nullish values]
- */
+// Versioned merges require metadata fresh from remote.
const updateFilesPrivateMagicMetadata = async (
files: EnteFile[],
updates: FilePrivateMagicMetadataData,
@@ -138,41 +73,16 @@ const updateFilesPrivateMagicMetadata = async (
),
});
-/**
- * The payload of the remote requests for updating the magic metadata of a
- * single item (file or collection).
- */
export interface UpdateMagicMetadataRequest {
- /**
- * File or collection ID
- */
id: number;
- /**
- * The updated magic metadata.
- *
- * Remote usually enforces the following constraints when we're trying to
- * update already existing data.
- *
- * - The version should be same as the existing version.
- * - The count should be greater than or equal to the existing count.
- */
+ // Version must match remote; count must not decrease.
magicMetadata: RemoteMagicMetadata;
}
-/**
- * The payload of the remote requests for updating the magic metadata of a
- * multiple items.
- *
- * Currently this is only used by endpoints that update magic metadata for a
- * list of files.
- */
export interface UpdateMultipleMagicMetadataRequest {
metadataList: UpdateMagicMetadataRequest[];
}
-/**
- * Update the private magic metadata of a list of files on remote.
- */
const putFilesMagicMetadata = async (
updateRequest: UpdateMultipleMagicMetadataRequest,
) =>
@@ -184,66 +94,18 @@ const putFilesMagicMetadata = async (
}),
);
-/**
- * Update the file name of the provided file on remote.
- *
- * Remote only, does not modify local state.
- *
- * The file name of an {@link EnteFile} is stored in its public magic metadata,
- * so this function in effect updates the public magic metadata of the given
- * file on remote.
- *
- * @param file The file whose file name we want to change.
- *
- * @param newFileName The new file name of the file.
- */
export const updateFileFileName = (file: EnteFile, newFileName: string) =>
updateFilePublicMagicMetadata(file, { editedName: newFileName });
-/**
- * Update the caption associated with the provided file on remote.
- *
- * Remote only, does not modify local state.
- *
- * The caption of an {@link EnteFile} is stored in its public magic metadata, so
- * this function in effect updates the public magic metadata of the given file
- * on remote.
- *
- * @param file The file whose file name we want to change.
- *
- * @param caption The caption associated with the file.
- *
- * Fields in magic metadata cannot be removed after being added, so to reset the
- * caption to the default (no value) state pass a blank string.
- */
+// Magic metadata fields cannot be removed; blank resets the caption.
export const updateFileCaption = (file: EnteFile, caption: string) =>
updateFilePublicMagicMetadata(file, { caption });
-/**
- * Update the public magic metadata of a file on remote.
- *
- * Remote only, does not modify local state.
- *
- * @param file The list of files whose magic metadata we want to update.
- *
- * @param updates A non-empty but otherwise arbitrary subset of
- * {@link FilePrivateMagicMetadataData} entries.
- *
- * See: [Note: Magic metadata data cannot have nullish values]
- */
export const updateFilePublicMagicMetadata = async (
file: EnteFile,
updates: FilePublicMagicMetadataData,
) => updateFilesPublicMagicMetadata([file], updates);
-/**
- * Update the public magic metadata of a list of files on remote.
- *
- * Remote only, does not modify local state.
- *
- * This is a variant of {@link updateFilePrivateMagicMetadata} that works with
- * the {@link pubMagicMetadata} of the given files.
- */
const updateFilesPublicMagicMetadata = async (
files: EnteFile[],
updates: FilePublicMagicMetadataData,
@@ -263,9 +125,6 @@ const updateFilesPublicMagicMetadata = async (
),
});
-/**
- * Update the public magic metadata of a list of files on remote.
- */
const putFilesPublicMagicMetadata = async (
updateRequest: UpdateMultipleMagicMetadataRequest,
) =>
@@ -277,20 +136,6 @@ const putFilesPublicMagicMetadata = async (
}),
);
-/**
- * Update the location (latitude and longitude) for a list of files on remote.
- *
- * Remote only, does not modify local state.
- *
- * The location of an {@link EnteFile} is stored in its public magic metadata
- * as the `lat` and `long` fields.
- *
- * @param files The list of files whose location we want to update.
- *
- * @param lat The new latitude.
- *
- * @param long The new longitude.
- */
export const updateFilesLocation = async (
files: EnteFile[],
lat: number,
diff --git a/web/packages/new/photos/services/ml/db.ts b/web/packages/new/photos/services/ml/db.ts
index 6372313f6f..e2606a8e70 100644
--- a/web/packages/new/photos/services/ml/db.ts
+++ b/web/packages/new/photos/services/ml/db.ts
@@ -4,39 +4,6 @@ import type { LocalCLIPIndex } from "./clip";
import type { FaceCluster } from "./cluster";
import type { LocalFaceIndex } from "./face";
-/**
- * ML DB schema.
- *
- * The "ML" database is made of the lower level "index" object stores, and
- * higher level "cluster" object stores.
- *
- * The index related object stores are the following:
- *
- * - "file-status": Contains {@link FileStatus} objects, one for each
- * {@link EnteFile} that the ML subsystem knows about. Periodically (and when
- * required), this is synced with the list of files that the current client
- * knows about locally.
- *
- * - "face-index": Contains {@link LocalFaceIndex} objects, either indexed
- * locally or fetched from remote.
- *
- * - "clip-index": Contains {@link LocalCLIPIndex} objects, either indexed
- * locally or fetched from remote.
- *
- * These three stores are keyed by {@link fileID}. The "file-status" contains
- * book-keeping about the indexing process (whether or not a file needs
- * indexing, or if there were errors doing so), while the other stores contain
- * the actual indexing results.
- *
- * In tandem, these serve as the underlying storage for the indexes maintained
- * in the ML database.
- *
- * The face clustering related object stores are the following:
- *
- * - "face-cluster": Contains {@link FaceCluster} objects, one for each cluster
- * of faces that either the clustering algorithm produced locally. It is
- * indexed by the cluster ID.
- */
interface MLDBSchema extends DBSchema {
"file-status": {
key: number;
@@ -46,45 +13,16 @@ interface MLDBSchema extends DBSchema {
"face-index": { key: number; value: LocalFaceIndex };
"clip-index": { key: number; value: LocalCLIPIndex };
"face-cluster": { key: string; value: FaceCluster };
- /* Unused */
"cluster-group": { key: string; value: unknown };
}
interface FileStatus {
- /** The ID of the {@link EnteFile} whose indexing status we represent. */
fileID: number;
- /**
- * The status of the file.
- *
- * - "indexable" - This file is something that we can index, but it is yet
- * to be indexed.
- *
- * - "indexed" - We have a corresponding entry for this file in the
- * "face-index" _and_ "clip-index" object stores (either indexed locally
- * or fetched from remote).
- *
- * - "failed" - Indexing was attempted but failed.
- *
- * If you haven't heard the word "index" to the point of zoning out, we also
- * have a (IndexedDB) "index" on the status field to allow us to efficiently
- * select or count {@link fileIDs} that fall into various buckets.
- */
status: "indexable" | "indexed" | "failed";
- /**
- * The number of times attempts to index this file failed.
- *
- * It counts failure across all index types.
- *
- * This is guaranteed to be `0` for files with status "indexed".
- */
failureCount: number;
}
-/**
- * A lazily-created, cached promise for ML DB.
- *
- * See: [Note: Caching IDB instances in separate execution contexts].
- */
+// Workers cache separate connections; terminate them before deleting this DB.
let _mlDB: ReturnType<typeof openMLDB> | undefined;
const openMLDB = async () => {
@@ -121,16 +59,8 @@ const openMLDB = async () => {
return db;
};
-/**
- * @returns a lazily created, cached connection to the ML DB.
- */
const mlDB = () => (_mlDB ??= openMLDB());
-/**
- * Clear any data stored in the ML DB.
- *
- * This is meant to be called during logout on the main thread.
- */
export const clearMLDB = async () => {
try {
if (_mlDB) (await _mlDB).close();
@@ -148,15 +78,6 @@ export const clearMLDB = async () => {
});
};
-/**
- * Save the given {@link faceIndex} and {@link clipIndex}, and mark the file as
- * "indexed".
- *
- * This function adds a new entry for the indexes, overwriting any existing ones
- * (No merging is performed, the existing entry is unconditionally overwritten).
- * The file status is also updated to "indexed", and the failure count is reset
- * to 0.
- */
export const saveIndexes = async (
faceIndex: LocalFaceIndex,
clipIndex: LocalCLIPIndex,
@@ -164,6 +85,7 @@ export const saveIndexes = async (
const { fileID } = faceIndex;
const db = await mlDB();
+ // Status must not say indexed unless both indexes commit.
const tx = db.transaction(
["file-status", "face-index", "clip-index"],
"readwrite",
@@ -179,51 +101,27 @@ export const saveIndexes = async (
]);
};
-/**
- * Return a new object suitable for use as the initial value of the entry for a
- * file in the file status store.
- */
const newFileStatus = (fileID: number): FileStatus => ({
fileID,
status: "indexable",
failureCount: 0,
});
-/**
- * Return the {@link FaceIndex}, if any, for {@link fileID}.
- */
export const savedFaceIndex = async (fileID: number) => {
const db = await mlDB();
return db.get("face-index", fileID);
};
-/**
- * Return all face indexes present locally.
- */
export const savedFaceIndexes = async () => {
const db = await mlDB();
return await db.getAll("face-index");
};
-/**
- * Return all CLIP indexes present locally.
- */
export const savedCLIPIndexes = async () => {
const db = await mlDB();
return await db.getAll("clip-index");
};
-/**
- * Record the existence of a file so that entities in the ML universe know about
- * it (e.g. can index it if it is new and it needs indexing).
- *
- * @param fileID The ID of an {@link EnteFile}.
- *
- * This function does not overwrite existing entries. If an entry already exists
- * for the given {@link fileID} (e.g. if it was indexed and
- * {@link saveFaceIndex} called with the result), its existing status remains
- * unperturbed.
- */
export const addFileEntry = async (fileID: number) => {
const db = await mlDB();
const tx = db.transaction("file-status", "readwrite");
@@ -232,27 +130,6 @@ export const addFileEntry = async (fileID: number) => {
return tx.done;
};
-/**
- * Update entries in ML DB to align with the state of local files outside ML DB.
- *
- * @param localFileIDs IDs of all the files that the client is aware of.
- *
- * @param localTrashFilesIDs IDs of all the files in trash.
- *
- * This function then updates the state of file entries in ML DB to the be in
- * sync with these provided local file IDs.
- *
- * - Files that are present locally but are not yet in ML DB get a fresh entry
- * in face DB (and are marked as indexable).
- *
- * - Files that are not present locally (nor are in trash) but still exist in ML
- * DB are removed from ML DB (including any indexes).
- *
- * - Files that are not present locally but are in the trash are retained in ML
- * DB if their status is "indexed"; otherwise they too are removed. This is to
- * prevent churn, otherwise they'll get unnecessarily reindexed again if the
- * user restores them from trash before permanent deletion.
- */
export const updateAssumingLocalFiles = async (
localFileIDs: number[],
localTrashFilesIDs: Set<number>,
@@ -273,15 +150,14 @@ export const updateAssumingLocalFiles = async (
const newFileIDs = localFileIDs.filter((id) => !fdb.has(id));
const removedFileIDs = fdbFileIDs.filter((id) => {
- if (local.has(id)) return false; // Still exists.
+ if (local.has(id)) return false;
if (localTrashFilesIDs.has(id)) {
- // Exists in trash.
+ // Retain finished indexes to avoid reindexing a restored file.
if (fdbIndexed.has(id)) {
- // But is already indexed, so let it be.
return false;
}
}
- return true; // Remove.
+ return true;
});
await Promise.all(
@@ -299,10 +175,6 @@ export const updateAssumingLocalFiles = async (
);
};
-/**
- * Remove all "failed" file status entries so that we again attempt to index
- * those files the next time indexing happens.
- */
export const resetFailedFileStatuses = async () => {
const db = await mlDB();
const tx = db.transaction("file-status", "readwrite");
@@ -313,13 +185,6 @@ export const resetFailedFileStatuses = async () => {
await Promise.all([ids.map((id) => tx.store.delete(id)), tx.done].flat());
};
-/**
- * Return the count of files that can be indexed, have been indexed, and which
- * have been marked as having failed when attempting to index them.
- *
- * The total number of files that are within the purview of the indexer is
- * indexable + indexed + failed.
- */
export const savedIndexCounts = async () => {
const db = await mlDB();
const tx = db.transaction("file-status", "readonly");
@@ -335,21 +200,10 @@ export const savedIndexCounts = async () => {
return { indexableCount, indexedCount, failedCount };
};
-/**
- * Return a list of fileIDs that need to be indexed.
- *
- * This list is from the universe of the file IDs that the face DB knows about
- * (we can use {@link addFileEntry} to inform it about new files). From this
- * universe, we filter out fileIDs the files corresponding to which have already
- * been indexed, or which should be ignored.
- *
- * @param count Limit the result to up to {@link count} items. If there are more
- * than {@link count} items present, the files with the higher file IDs (which
- * can be taken as a approximate for their creation order) are preferred.
- */
export const readNextIndexableFileIDs = async (count: number) => {
const db = await mlDB();
const tx = db.transaction("file-status", "readonly");
+ // Higher file IDs approximate newer files; index them first.
let cursor = await tx.store
.index("status")
.openKeyCursor(IDBKeyRange.only("indexable"), "prev");
@@ -362,18 +216,6 @@ export const readNextIndexableFileIDs = async (count: number) => {
return result;
};
-/**
- * Increment the failure count associated with the given {@link fileID}.
- *
- * @param fileID The ID of an {@link EnteFile}.
- *
- * If an entry does not exist yet for the given file, then a new one is created
- * and its failure count is set to 1. Otherwise the failure count of the
- * existing entry is incremented.
- *
- * This count is across all different types of indexing (face, CLIP) that happen
- * on the file.
- */
export const markIndexingFailed = async (fileID: number) => {
const db = await mlDB();
const tx = db.transaction("file-status", "readwrite");
@@ -383,20 +225,11 @@ export const markIndexingFailed = async (fileID: number) => {
await Promise.all([tx.store.put(fileStatus), tx.done]);
};
-/**
- * Return all face clusters present locally.
- */
export const savedFaceClusters = async () => {
const db = await mlDB();
return db.getAll("face-cluster");
};
-/**
- * Replace the face clusters stored locally with the given ones.
- *
- * This function deletes all entries from the face cluster object store, and
- * then inserts the given {@link clusters} into it.
- */
export const saveFaceClusters = async (clusters: FaceCluster[]) => {
const db = await mlDB();
const tx = db.transaction("face-cluster", "readwrite");
diff --git a/web/packages/new/photos/services/ml/face.ts b/web/packages/new/photos/services/ml/face.ts
index 15a9f69512..54631d9317 100644
--- a/web/packages/new/photos/services/ml/face.ts
+++ b/web/packages/new/photos/services/ml/face.ts
@@ -1,216 +1,51 @@
import { assertionFailed } from "ente-base/assert";
-/**
- * The version of the face indexing pipeline implemented by the current client.
- */
export const faceIndexingVersion = 1;
-/**
- * The faces in a file (and an embedding for each of them).
- *
- * This interface describes the format of face related data (aka "face index")
- * for a file. This is the common subset that is present in both the fields that
- * are persisted on remote ({@link RemoteFaceIndex}) and locally
- * ({@link LocalFaceIndex}).
- *
- * - Face detections and embeddings (collectively called as the face index) are
- * generated by the current client when uploading a file, or when noticing a
- * file which doesn't yet have a face index. They are then uploaded (E2EE) to
- * remote, and the relevant bits also saved locally in the ML DB for
- * subsequent lookup or clustering.
- *
- * - This face index is then fetched by subsequent clients to avoid them having
- * to reindex (indexing faces is a costly operation, esp. for mobile clients).
- *
- * In both these scenarios (whether generated locally or fetched from remote),
- * we end up with an some data described by this {@link FaceIndex} interface. We
- * modify it slightly, adding envelopes, when saving them locally or uploading
- * them to remote - those variations are described by the {@link LocalFaceIndex}
- * and {@link RemoteFaceIndex} types respectively.
- */
export interface FaceIndex {
- /**
- * The width (in px) of the image (file).
- *
- * Having the image dimensions here is useful since the coordinates inside
- * the {@link Face}s are all normalized (0 to 1) to the width and height of
- * the image.
- */
width: number;
- /**
- * The height (in px) of the image (file).
- */
height: number;
- /**
- * The list of faces (and their embeddings) detected in the file.
- *
- * Each of the items is a {@link Face}, containing the result of a face
- * detection, and an embedding for that detected face.
- */
faces: Face[];
}
export type RemoteFaceIndex = FaceIndex & {
- /**
- * An integral version number of the indexing algorithm / pipeline.
- *
- * [Note: Embedding versions]
- *
- * Embeddings have an associated version so it is possible for us to make
- * backward compatible updates to the indexing process on newer clients.
- *
- * Clients agree out of band what a particular version means, and guarantee
- * that an embedding with a particular version will be the same (to epsilon
- * cosine similarity) irrespective of the client that indexed the file.
- *
- * If we bump the version of same model (say when indexing on a newer
- * client), we will do it in a manner that older client will be able to
- * consume the response. The schema should not change in non-additive
- * manners. For example, say if we improve blur detection, older client
- * should just consume embeddings with a newer version and not try to index
- * the file again locally.
- *
- * When fetching from remote, if we get an embedding with version that is
- * older than the version the client supports, then the client should ignore
- * it. This way, the file will get reindexed locally and an embedding with a
- * newer version will also get saved to remote.
- *
- * In the case where the changes are not backward compatible and can only be
- * consumed by clients by making code changes, then we will introduce a new
- * subtype (top level key) in the derived data.
- */
+ // Same versions must be cross-client compatible.
+ // Older versions are ignored and reindexed.
+ // Breaking formats require a new top-level subtype.
version: number;
- /**
- * The UA for the client which generated this embedding.
- */
client: string;
- /**
- * Bitmask describing the runtime that generated this index. An absent
- * value on legacy remote data is parsed as zero.
- */
flags: number;
};
-export type LocalFaceIndex = FaceIndex & {
- /**
- * The ID of the {@link EnteFile} whose index this is.
- *
- * This is used as the primary key when storing the index locally (An
- * {@link EnteFile} is guaranteed to have its fileID be unique in the
- * namespace of the user. Even if someone shares a file with the user the
- * user will get a file entry with a fileID unique to them).
- */
- fileID: number;
-};
+export type LocalFaceIndex = FaceIndex & { fileID: number };
-/**
- * A face detected in a file, and an embedding for this detected face.
- *
- * During face indexing, we first detect all the faces in a particular file.
- * Then for each such detected region, we compute an embedding of that part of
- * the file. Together, this detection region and the emedding travel together in
- * this {@link Face} interface.
- */
export interface Face {
- /**
- * A unique identifier for the face.
- *
- * This ID is guaranteed to be unique for all the faces detected in all the
- * files for the user. In particular, each file can have multiple faces but
- * they all will get their own unique {@link faceID}.
- *
- * This ID is also meant to be stable across reindexing. That is, if the
- * same algorithm and hyperparameters are used to reindex the file, then it
- * should result in the same face IDs. This allows us leeway in letting
- * unnecessary reindexing happen in rare cases without invalidating the
- * clusters that rely on the presence of the given face ID.
- *
- * Finally, this face ID is not completely opaque. It consists of underscore
- * separated components, the first of which is the ID of the
- * {@link EnteFile} to which this face belongs. Client code can rely on this
- * structure and can parse it if needed using {@link fileIDFromFaceID}.
- */
+ // Stable across equivalent reindexing and prefixed with `${fileID}_`.
faceID: string;
- /**
- * The face detection. Describes the region within the image that was
- * detected to be a face, and a set of landmarks (e.g. "eyes") of the
- * detection.
- *
- * All coordinates are relative to and normalized by the image's dimension,
- * i.e. they have been normalized to lie between 0 and 1, with 0 being the
- * left (or top) and 1 being the width (or height) of the image.
- */
- detection: {
- /**
- * The region within the image that contains the face.
- *
- * All coordinates and sizes are between 0 and 1, normalized by the
- * dimensions of the image.
- * */
- box: Box;
- /**
- * Face "landmarks", e.g. eyes.
- *
- * The exact landmarks and their order depends on the face detection
- * algorithm being used.
- *
- * The coordinatesare between 0 and 1, normalized by the dimensions of
- * the image.
- */
- landmarks: Point[];
- };
- /**
- * An correctness probability (0 to 1) that the face detection algorithm
- * gave to the detection. Higher values are better.
- */
+ // Detection coordinates are normalized to [0, 1].
+ detection: { box: Box; landmarks: Point[] };
score: number;
- /**
- * The computed blur for the detected face.
- *
- * The exact semantics and range for these (floating point) values depend on
- * the face indexing algorithm / pipeline version being used.
- * */
blur: number;
- /**
- * An embedding for the face.
- *
- * This is an opaque numeric (signed floating point) vector whose semantics
- * and length depend on the version of the face indexing algorithm /
- * pipeline that we are using. However, within a set of embeddings with the
- * same version, the property is that two such embedding vectors will be
- * "cosine similar" to each other if they are both faces of the same person.
- */
embedding: number[];
}
-/** The x and y coordinates of a point. */
export interface Point {
x: number;
y: number;
}
-/** The dimensions of something, say an image. */
export interface Dimensions {
width: number;
height: number;
}
-/** A rectangle given by its top left coordinates and dimensions. */
export interface Box {
- /** The x coordinate of the the top left (xMin). */
x: number;
- /** The y coordinate of the top left (yMin). */
y: number;
- /** The width of the box. */
width: number;
- /** The height of the box. */
height: number;
}
-/**
- * Extract the fileID of the {@link EnteFile} to which the face belongs from its
- * faceID.
- */
export const fileIDFromFaceID = (faceID: string) => {
const fileID = parseInt(faceID.split("_")[0] ?? "");
if (isNaN(fileID)) {
diff --git a/web/packages/new/photos/services/ml/index.ts b/web/packages/new/photos/services/ml/index.ts
index 852f1c1dcc..0dd73d5a88 100644
--- a/web/packages/new/photos/services/ml/index.ts
+++ b/web/packages/new/photos/services/ml/index.ts
@@ -1,7 +1,3 @@
-/**
- * @file Main thread interface to the ML subsystem.
- */
-
import { proxy, transfer } from "comlink";
import { ensureLocalUser } from "ente-accounts/services/user";
import { isDesktop } from "ente-base/app";
@@ -46,99 +42,23 @@ import {
import { MLWorker } from "./worker";
import type { CLIPMatches } from "./worker-types";
-/**
- * Internal state of the ML subsystem.
- *
- * These are essentially cached values used by the functions of this module.
- *
- * They will be cleared on logout.
- */
class MLState {
- /**
- * In-memory flag that tracks if ML is enabled.
- *
- * - On app start, this is read from local storage during {@link initML}.
- *
- * - It gets updated when we pull from remote (so if the user
- * enables/disables ML on a different device, this local value will also
- * become true/false).
- *
- * - It gets updated when the user enables/disables ML on this device.
- *
- * - It is cleared in {@link logoutML}.
- */
isMLEnabled = false;
-
- /**
- * Cached instance of the {@link ComlinkWorker} that wraps our web worker.
- */
comlinkWorker: Promise<ComlinkWorker<typeof MLWorker>> | undefined;
-
- /**
- * `true` if a sync is currently in progress.
- */
isSyncing = false;
-
- /**
- * Subscriptions to {@link MLStatus} updates attached using
- * {@link mlStatusSubscribe}.
- */
mlStatusListeners: (() => void)[] = [];
-
- /**
- * Snapshot of the {@link MLStatus} returned by the {@link mlStatusSnapshot}
- * function.
- */
mlStatusSnapshot: MLStatus | undefined;
-
- /**
- * Subscriptions to updates to the {@link PeopleState} attached using
- * {@link peopleStateSubscribe}.
- */
peopleStateListeners: (() => void)[] = [];
-
- /**
- * Snapshot of the {@link PeopleState} return by the
- * {@link peopleStateSnapshot} function.
- *
- * It will be `undefined` only if ML is disabled. Otherwise, it will be an
- * empty array even if the snapshot is pending its first sync.
- */
peopleStateSnapshot: PeopleState | undefined;
-
- /**
- * `true` if a reset has been requested via
- * {@link retryIndexingFailuresIfNeeded}.
- */
needsResetFailures = false;
-
- /**
- * In flight face crop regeneration promises indexed by the IDs of the files
- * whose faces we are regenerating.
- */
inFlightFaceCropRegens = new Map<number, Promise<void>>();
-
- /**
- * Cached object URLs to face crops that we have previously vended out.
- *
- * The cache is only cleared on logout.
- */
faceCropObjectURLCache = new Map<string, string>();
}
-/** State shared by the functions in this module. See {@link MLState}. */
let _state = new MLState();
-/**
- * Tracks if {@link initML} has already run for the current session.
- *
- * Some callers (notably the Next.js app shell) can end up invoking
- * {@link initML} multiple times because of re-renders or hot reloads. Without
- * this guard we'd reset {@link peopleStateSnapshot} on every invocation and
- * discard the list of people until the next sync repopulates it.
- */
+// Reinitializing would erase people until the next sync.
let _didInitML = false;
-/** Lazily created, cached, instance of {@link MLWorker}. */
const worker = () =>
(_state.comlinkWorker ??= createComlinkWorker()).then((cw) => cw.remote);
@@ -150,7 +70,6 @@ const createComlinkWorker = async () => {
workerDidLoseElectronPort,
};
- // Obtain a message port from the Electron layer.
const messagePort = await createUtilityProcess(electron, "ml");
const cw = new ComlinkWorker<typeof MLWorker>(
@@ -159,22 +78,12 @@ const createComlinkWorker = async () => {
);
await cw.remote.then((w) =>
- // Forward the port to the web worker.
w.init(transfer(messagePort, [messagePort]), proxy(delegate)),
);
return cw;
};
-/**
- * Terminate {@link worker} (if any).
- *
- * This is useful during logout to immediately stop any background ML operations
- * that are in-flight for the current user. After the user logs in again, a new
- * {@link worker} will be created on demand for subsequent usage.
- *
- * It is also called when the user pauses or disables ML.
- */
export const terminateMLWorker = async () => {
if (_state.comlinkWorker) {
await _state.comlinkWorker.then((cw) => cw.terminate());
@@ -182,16 +91,8 @@ export const terminateMLWorker = async () => {
}
};
-/**
- * Return true if the current client supports ML.
- *
- * ML currently only works when we're running in our desktop app.
- */
export const isMLSupported = isDesktop;
-/**
- * Initialize the ML subsystem if the user has enabled it in preferences.
- */
export const initML = () => {
if (_didInitML) return;
_state.isMLEnabled = isMLEnabledLocal();
@@ -199,12 +100,8 @@ export const initML = () => {
_didInitML = true;
};
+// Terminate the worker first; each context caches its own IDB connection.
export const logoutML = async () => {
- // `terminateMLWorker` is conceptually also part of this sequence, but for
- // the reasons mentioned in [Note: Caching IDB instances in separate
- // execution contexts], it gets called first in the logout sequence, and
- // then this function (`logoutML`) gets called at a later point in time.
-
[..._state.faceCropObjectURLCache.values()].forEach((url) =>
URL.revokeObjectURL(url),
);
@@ -213,38 +110,16 @@ export const logoutML = async () => {
await clearMLDB();
};
-/**
- * Return true if the user has enabled machine learning in their preferences.
- *
- * Enabling ML enables in both locally by persisting a local storage flag, and
- * sets a flag on remote so that the user's other devices can also enable it
- * when they next sync with remote.
- */
-export const isMLEnabled = () =>
- // Implementation note: Keep it fast, it might be called frequently.
- _state.isMLEnabled;
-
-/**
- * Enable ML.
- *
- * Persist the user's preference both locally and on remote, and trigger a sync.
- */
+export const isMLEnabled = () => _state.isMLEnabled;
export const enableML = async () => {
await updateIsMLEnabledRemote(true);
setIsMLEnabledLocal(true);
_state.isMLEnabled = true;
setInterimScheduledStatus();
resetPeopleStateSnapshot();
- // Trigger updates, but don't wait for them to finish.
void updateMLStatusSnapshot().then(() => mlSync("enable-ml"));
};
-/**
- * Disable ML.
- *
- * Stop any in-progress ML tasks, and persist the user's preference both locally
- * and on remote.
- */
export const disableML = async () => {
await updateIsMLEnabledRemote(false);
setIsMLEnabledLocal(false);
@@ -255,104 +130,33 @@ export const disableML = async () => {
resetPeopleStateSnapshot();
};
-/**
- * Local storage key for {@link isMLEnabledLocal}.
- */
const mlLocalKey = "mlEnabled";
-/**
- * Return true if our local persistence thinks that ML is enabled.
- *
- * This setting is persisted locally (in local storage). It is not synced with
- * remote and only tracks if ML is enabled locally.
- *
- * The remote status is tracked with a separate {@link isMLEnabledRemote} flag
- * that is synced with remote.
- */
const isMLEnabledLocal = () => localStorage.getItem(mlLocalKey) == "1";
-/**
- * Update the (locally stored) value of {@link isMLEnabledLocal}.
- */
const setIsMLEnabledLocal = (enabled: boolean) =>
enabled
? localStorage.setItem(mlLocalKey, "1")
: localStorage.removeItem(mlLocalKey);
-/**
- * For historical reasons, this is called "faceSearchEnabled" (it started off as
- * a flag to ensure we have taken the face recognition consent from the user).
- *
- * Now it tracks the status of ML in general (which includes faces + consent).
- */
+// This legacy key now controls all ML, not only face search.
const mlRemoteKey = "faceSearchEnabled";
-/**
- * Return `true` if the flag to enable ML is set on remote.
- */
const getIsMLEnabledRemote = () => getRemoteFlag(mlRemoteKey);
-/**
- * Update the remote flag that tracks the user's ML preference.
- */
const updateIsMLEnabledRemote = (enabled: boolean) =>
updateRemoteFlag(mlRemoteKey, enabled);
-/**
- * Reset failures so that indexing is attempted again.
- *
- * When indexing of some individual files fails for non-retriable reasons, we
- * mark those as failures locally.
- *
- * See: [Note: Transient and permanent indexing failures].
- *
- * Sometimes we might wish to reattempt these though (e.g. when adding support
- * for more file formats).
- *
- * In such cases, this function can be called early on (during an app version
- * upgrade) to set an in-memory flag which tell us that before attemepting a
- * sync, we should reset existing failed statii.
- *
- * Since this is not a critical operation, we only keep this as an in-memory
- * flag, failure to honor this will not have permanent repercussions (e.g. the
- * file would eventually get indexed on mobile, or during logout / login, or
- * during the next time an reattempt is made).
- */
export const retryIndexingFailuresIfNeeded = () => {
_state.needsResetFailures = true;
};
-/**
- * Update our local ML status with the latest value from remote.
- *
- * This is called an at early point in the global sync sequence, without waiting
- * for the potentially long file information sync to complete.
- *
- * It checks with remote if the ML flag is set, and updates our local flag to
- * reflect that value.
- *
- * To perform the actual ML data pull, use {@link mlSync}.
- */
export const pullMLStatus = async () => {
_state.isMLEnabled = await getIsMLEnabledRemote();
setIsMLEnabledLocal(_state.isMLEnabled);
return updateMLStatusSnapshot();
};
-/**
- * Perform a ML sync, whatever is applicable.
- *
- * This is called during the global pull sequence, after files information have
- * been pulled with remote.
- *
- * If ML is enabled, it pulls any missing embeddings from remote and starts
- * indexing to backfill any missing values. It also pulls cgroups and updates
- * the search service to use the latest values. Finally, it uses the latest
- * files, faces and cgroups to update the people shown in the UI.
- *
- * This will only have an effect if {@link pullMLStatus} has been called at
- * least once prior to calling this in the pull sequence.
- */
export const mlSync = async (reason: ClusterFacesReason = "ml-sync") => {
if (!_state.isMLEnabled) return;
if (_state.isSyncing) return;
@@ -360,18 +164,11 @@ export const mlSync = async (reason: ClusterFacesReason = "ml-sync") => {
try {
if (_state.needsResetFailures) {
- // CAS. See documentation for retryIndexingFailures why swapping
- // the flag before performing the operation is fine.
_state.needsResetFailures = false;
await resetFailedFileStatuses();
}
- // Dependency order for the sync
- //
- // files -> faces -> cgroups -> clusters -> people
- //
-
- // Fetch indexes, or index locally if needed.
+ // Keep the order: files, faces, cgroups, clusters, then people.
await worker().then((w) => w.index());
await updateClustersAndPeople(reason);
@@ -383,31 +180,14 @@ export const mlSync = async (reason: ClusterFacesReason = "ml-sync") => {
const updateClustersAndPeople = async (reason: ClusterFacesReason) => {
const masterKey = await ensureMasterKeyFromSession();
- // Fetch existing cgroups from remote.
await pullUserEntities("cgroup", masterKey);
- // Generate or update local clusters.
await (await worker()).clusterFaces(masterKey, reason);
- // Update the people shown in the UI.
await updatePeopleState();
};
-/**
- * A debounced variant of {@link updateClustersAndPeople} suitable for use
- * during potential in-progress uploads.
- *
- * The debounce uses a long interval (30 seconds) to avoid unnecessary reruns of
- * the expensive clustering as individual files get uploaded. Usually we
- * wouldn't get here as the live queue will keep getting refilled and the worker
- * would keep ticking, but it is possible, depending on timing, for the queue to
- * drain in the middle of uploads too.
- *
- * Ideally, we'd like to do the cluster update just once when the upload has
- * completed, however currently we don't have access to {@link uploadManager}
- * from here. So this gets us near that ideal, without adding too much impact or
- * requiring us to be aware of the uploadManager status.
- */
+// Uploads arrive one by one; avoid reclustering after every file.
const debounceUpdateClustersAndPeople = pDebounce(
updateClustersAndPeople,
30 * 1e3,
@@ -421,24 +201,6 @@ const workerDidLoseElectronPort = () => {
const workerDidUnawaitedIndex = () =>
void debounceUpdateClustersAndPeople("live-upload-index");
-/**
- * Run indexing on a file which was uploaded from this client.
- *
- * Indexing only happens if ML is enabled and we're running in the desktop app
- * as it is resource intensive.
- *
- * This function is called by the uploader when it uploads a new file from this
- * client, giving us the opportunity to index it live. This is only an
- * optimization - if we don't index it now it'll anyways get indexed later as
- * part of the batch jobs, but that might require downloading the file's
- * contents again.
- *
- * @param file The {@link EnteFile} that got uploaded.
- *
- * @param processableItem The item that was uploaded. This can be used to get at
- * the contents of the file that got uploaded. In case of live photos, this is
- * the image part of the live photo that was uploaded.
- */
export const indexNewUpload = (
file: EnteFile,
processableUploadItem: ProcessableUploadItem,
@@ -451,51 +213,14 @@ export const indexNewUpload = (
};
export type MLStatus =
- | { phase: "disabled" /* The ML remote flag is off */ }
+ | { phase: "disabled" }
| {
- /**
- * Which phase we are in within the indexing pipeline when viewed
- * across the user's entire library:
- *
- * - "scheduled": A ML job is scheduled. Likely there are files we
- * know of that have not been indexed, but is also the state before
- * the first run of the indexer after app start.
- *
- * - "indexing": The indexer is currently running.
- *
- * - "fetching": The indexer is currently running, but we're primarily
- * fetching indexes for existing files.
- *
- * - "clustering": All files we know of have been indexed, and we are
- * now clustering the faces that were found.
- *
- * - "done": ML indexing and face clustering is complete for the
- * user's library.
- */
phase: "scheduled" | "indexing" | "fetching" | "clustering" | "done";
- /**
- * `true` if the phase is "done" but a significant fraction of files
- * were marked as failed when indexing.
- *
- * This is not expected to happen normally, and points to a some
- * systematic error in the environment (e.g. ONNX couldn't run).
- */
phaseFailed?: boolean;
- /**
- * The number of files that have already been indexed.
- */
nSyncedFiles: number;
- /**
- * The total number of files that are eligible for indexing.
- */
nTotalFiles: number;
};
-/**
- * A function that can be used to subscribe to updates in the ML status.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
export const mlStatusSubscribe = (onChange: () => void): (() => void) => {
_state.mlStatusListeners.push(onChange);
return () => {
@@ -505,34 +230,16 @@ export const mlStatusSubscribe = (onChange: () => void): (() => void) => {
};
};
-/**
- * Return the last known, cached {@link MLStatus}.
- *
- * See also {@link mlStatusSubscribe}.
- *
- * This function can be safely called even if {@link isMLSupported} is `false`
- * (in such cases, it will always return `undefined`). This is so that it can be
- * unconditionally called as part of a React hook.
- *
- * A return value of `undefined` indicates that we're still performing the
- * asynchronous tasks that are needed to get the status.
- */
export const mlStatusSnapshot = (): MLStatus | undefined => {
if (!isMLSupported) return undefined;
const result = _state.mlStatusSnapshot;
- // We don't have it yet, trigger an update.
if (!result) triggerStatusUpdate();
return result;
};
-/**
- * Trigger an asynchronous update of the {@link MLStatus} snapshot, and return
- * without waiting for it to finish.
- */
const triggerStatusUpdate = () => void updateMLStatusSnapshot();
-/** Unconditionally update of the {@link MLStatus} snapshot. */
const updateMLStatusSnapshot = async () =>
setMLStatusSnapshot(await getMLStatus());
@@ -541,16 +248,11 @@ const setMLStatusSnapshot = (snapshot: MLStatus) => {
_state.mlStatusListeners.forEach((l) => l());
};
-/**
- * Compute the current state of the ML subsystem.
- */
const getMLStatus = async (): Promise<MLStatus> => {
if (!_state.isMLEnabled) return { phase: "disabled" };
const w = await worker();
- // The worker has a clustering progress set iff it is clustering. This
- // overrides other behaviours.
const clusteringProgress = await w.clusteringProgress;
if (clusteringProgress) {
return {
@@ -563,13 +265,7 @@ const getMLStatus = async (): Promise<MLStatus> => {
const { indexedCount, indexableCount, failedCount } =
await savedIndexCounts();
- // During live uploads, the indexable count remains zero even as the indexer
- // is processing the newly uploaded items. This is because these "live
- // queue" items do not yet have a "file-status" entry.
- //
- // So use the state of the worker as a guide for the phase, not the
- // indexable count.
-
+ // Live uploads lack file-status rows, so worker state wins over counts.
let phase: MLStatus["phase"];
let phaseFailed = false;
const state = await w.state;
@@ -590,16 +286,6 @@ const getMLStatus = async (): Promise<MLStatus> => {
};
};
-/**
- * When the user enables or resumes ML, we wish to give immediate feedback.
- *
- * So this is an intermediate state with possibly incorrect counts (but correct
- * phase) that is set immediately to trigger a UI update. It uses the counts
- * from the last known status, and just updates the phase.
- *
- * Once the worker is initialized and the correct counts fetched, this will
- * update to the correct state (should take less than a second).
- */
const setInterimScheduledStatus = () => {
let nSyncedFiles = 0,
nTotalFiles = 0;
@@ -614,11 +300,6 @@ const setInterimScheduledStatus = () => {
const workerDidUpdateStatus = throttled(updateMLStatusSnapshot, 2000);
-/**
- * A function that can be used to subscribe to updates to {@link Person}s.
- *
- * See: [Note: Snapshots and useSyncExternalStore].
- */
export const peopleStateSubscribe = (onChange: () => void): (() => void) => {
_state.peopleStateListeners.push(onChange);
return () => {
@@ -628,12 +309,7 @@ export const peopleStateSubscribe = (onChange: () => void): (() => void) => {
};
};
-/**
- * If ML is enabled, set the people snapshot to an empty array to indicate that
- * ML is enabled, but we're still reading in the set of people.
- *
- * Otherwise, if ML is disabled, set the people snapshot to `undefined`.
- */
+// Undefined means disabled; an empty state means enabled but loading or empty.
const resetPeopleStateSnapshot = () =>
setPeopleStateSnapshot(
_state.isMLEnabled
@@ -641,27 +317,13 @@ const resetPeopleStateSnapshot = () =>
: undefined,
);
-/**
- * Return the last known, cached {@link PeopleState}.
- *
- * See also {@link peopleStateSubscribe}.
- *
- * A return value of `undefined` indicates that ML is disabled. In all other
- * cases, the list of people will be either empty (if we're either still loading
- * the initial list of people, or if the user doesn't have any people), or,
- * well, non-empty.
- */
export const peopleStateSnapshot = () => _state.peopleStateSnapshot;
-// Update our, and the search subsystem's, snapshot of people state by
-// reconstructing it from the latest local state.
const updatePeopleState = async () => {
const state = await reconstructPeopleState();
- // Notify the search subsystem of the update (search only uses named ones).
setSearchPeople(filterNamedPeople(state.visiblePeople));
- // Update our in-memory state.
setPeopleStateSnapshot(state);
};
@@ -670,35 +332,17 @@ const setPeopleStateSnapshot = (snapshot: PeopleState | undefined) => {
_state.peopleStateListeners.forEach((l) => l());
};
-/**
- * Use CLIP to perform a natural language search over image embeddings.
- *
- * @param searchPhrase Normalized (trimmed and lowercased) search phrase.
- *
- * It returns file (IDs) that should be shown in the search results, each
- * annotated with its score.
- *
- * The result can also be `undefined`, which indicates that the download for the
- * ML model is still in progress (trying again later should succeed).
- */
export const clipMatches = (
searchPhrase: string,
): Promise<CLIPMatches | undefined> =>
worker().then((w) => w.clipMatches(searchPhrase));
-/**
- * A face ID annotated with the ID of the person or cluster with which it is
- * associated.
- */
export interface AnnotatedFaceID {
faceID: string;
personID: string;
personName: string | undefined;
}
-/**
- * Return the list of faces found in the given {@link file}.
- */
export const getAnnotatedFacesForFile = async (
file: EnteFile,
): Promise<AnnotatedFaceID[]> => {
@@ -721,26 +365,15 @@ export const getAnnotatedFacesForFile = async (
}
sortableFaces.sort((a, b) => {
- // If only one has a person name, prefer it.
if (a[0].personName && !b[0].personName) return -1;
if (!a[0].personName && b[0].personName) return 1;
- // Otherwise (both named or both unnamed) sort by their number of files.
return b[1] - a[1];
});
return sortableFaces.map(([f]) => f);
};
-/**
- * Return a URL to the face crop for the given face, regenerating it if needed.
- *
- * The resultant URL is cached (both the object URL itself, and the underlying
- * file crop blob used to generete it).
- *
- * @param faceID The id of the face whose face crop we want.
- *
- * @param file The {@link EnteFile} that contains this face.
- */
export const faceCrop = async (faceID: string, file: EnteFile) => {
+ // Returned object URLs are cache-owned; callers must not revoke them.
let inFlight = _state.inFlightFaceCropRegens.get(file.id);
if (!inFlight) {
@@ -763,11 +396,6 @@ export const faceCrop = async (faceID: string, file: EnteFile) => {
return url;
};
-/**
- * Check to see if any of the faces in the given file do not have a face crop
- * present locally. If so, then regenerate the face crops for all the faces in
- * the file (updating the "face-crops" {@link BlobCache}).
- */
const regenerateFaceCropsIfNeeded = async (file: EnteFile) => {
const index = await savedFaceIndex(file.id);
if (!index) return;
@@ -780,15 +408,6 @@ const regenerateFaceCropsIfNeeded = async (file: EnteFile) => {
if (needsRegen) await regenerateFaceCrops(file, index);
};
-/**
- * Convert a cluster into a named person, updating both remote and local state.
- *
- * @param name Name of the new cgroup user entity.
- *
- * @param cluster The underlying cluster to use to populate the cgroup.
- *
- * @returns The entity ID of the newly created cgroup.
- */
export const addCGroup = async (name: string, cluster: FaceCluster) => {
const id = await addUserEntity(
"cgroup",
@@ -805,18 +424,6 @@ export const addCGroup = async (name: string, cluster: FaceCluster) => {
return id;
};
-/**
- * Add a new cluster to an existing named person.
- *
- * If this cluster contains any faces that had previously been marked as not
- * belonging to the person, then they will be removed from the rejected list and
- * will get reassociated to the person.
- *
- * @param cgroup The existing cgroup underlying the person. This is the (remote)
- * user entity that will get updated.
- *
- * @param cluster The new cluster of faces to associate with this person.
- */
export const addClusterToCGroup = async (
cgroup: CGroup,
cluster: FaceCluster,
@@ -835,14 +442,6 @@ export const addClusterToCGroup = async (
return mlSync("add-cluster-to-cgroup");
};
-/**
- * Rename an existing named person.
- *
- * @param name The new name to use.
- *
- * @param cgroup The existing cgroup underlying the person. This is the (remote)
- * user entity that will get updated.
- */
export const renameCGroup = async (cgroup: CGroup, name: string) => {
await updateOrCreateUserEntities(
"cgroup",
@@ -852,19 +451,11 @@ export const renameCGroup = async (cgroup: CGroup, name: string) => {
return mlSync("rename-cgroup");
};
-/**
- * Delete an existing person.
- *
- * @param cgroup The existing cgroup underlying the person.
- */
export const deleteCGroup = async ({ id }: CGroup) => {
await deleteUserEntity(id);
return mlSync("delete-cgroup");
};
-/**
- * Change the pinned state of a person.
- */
export const setCGroupPinned = async (cgroup: CGroup, isPinned: boolean) => {
await updateOrCreateUserEntities(
"cgroup",
@@ -881,23 +472,10 @@ export const unpinCGroup = async (cgroup: CGroup) =>
setCGroupPinned(cgroup, false);
export interface ManualPersonAssignmentResult {
- /**
- * File IDs that were added to the person's manual assignment list.
- */
addedFileIDs: number[];
- /**
- * File IDs that were already associated with the person (either via a
- * detected face or via an existing manual assignment).
- */
alreadyAssignedFileIDs: number[];
}
-/**
- * Manually associate the given {@link fileIDs} with a remote cgroup ("person").
- *
- * The manual assignment is stored in the cgroup user entity data as an
- * unordered set of file IDs ({@link CGroupUserEntityData.manuallyAssigned}).
- */
export const addManualFileAssignmentsToPerson = async (
personID: string,
fileIDs: Iterable<number>,
@@ -916,7 +494,6 @@ export const addManualFileAssignmentsToPerson = async (
`addManualFileAssignmentsToPerson: missing cgroup ${personID}`,
);
- // File IDs already associated with the person via detected faces.
const existingClusterFileIDs = new Set<number>();
for (const cluster of cgroup.data.assigned) {
for (const faceID of cluster.faces) {
@@ -954,33 +531,18 @@ export const addManualFileAssignmentsToPerson = async (
masterKey,
);
- // Pull the updated entity to keep local updatedAt state in sync, and
- // reconstruct people state to reflect the new manual associations.
await pullUserEntities("cgroup", masterKey);
await updatePeopleState();
return { addedFileIDs, alreadyAssignedFileIDs };
};
-/**
- * Return suggestions for the given {@link person}.
- *
- * The suggestion computation happens in a web worker.
- *
- * Since the computation is happening in a web worker, and it doesn't
- * have access to any localStorage, we need to pass the currentUserID explicitly.
- * for the isHiddenCollection checks in the process.
- * */
export const suggestionsAndChoicesForPerson = async (person: CGroupPerson) =>
worker().then((w) =>
+ // Workers cannot read the browser session.
w.suggestionsAndChoicesForPerson(person, ensureLocalUser().id),
);
-/**
- * Implementation for the "save" action on the SuggestionsDialog.
- *
- * See {@link _applyPersonSuggestionUpdates} for more details.
- */
export const applyPersonSuggestionUpdates = async (
cgroup: CGroup,
updates: PersonSuggestionUpdates,
@@ -993,14 +555,6 @@ export const applyPersonSuggestionUpdates = async (
return mlSync("apply-person-suggestion-updates");
};
-/**
- * Ignore/hide a cluster.
- *
- * This converts the cluster into a cgroup so that it can be synced with remote,
- * setting the hidden flag so that it is not surfaced in the UI.
- *
- * @param cluster The {@link FaceCluster} to hide.
- */
export const ignoreCluster = async (cluster: FaceCluster) => {
await addUserEntity(
"cgroup",
diff --git a/web/packages/new/photos/services/ml/people.ts b/web/packages/new/photos/services/ml/people.ts
index f9680565e6..8ea002b8d2 100644
--- a/web/packages/new/photos/services/ml/people.ts
+++ b/web/packages/new/photos/services/ml/people.ts
@@ -18,236 +18,56 @@ import {
} from "./kvdb";
import { dotProduct } from "./math";
-/**
- * A cgroup ("cluster group") is a group of clusters (possibly containing just a
- * single cluster) that the user has interacted with.
- *
- * Interactions include hiding, merging and giving a name and/or a cover photo.
- *
- * The most frequent interaction is naming a {@link FaceCluster}, which promotes
- * it to a become a {@link CGroup}. The promotion comes with the
- * ability to be synced with remote (as a "cgroup" user entity).
- *
- * There after, the user may attach more clusters to the same cgroup.
- *
- * > A named cluster group can be thought of as a "person", though this is not
- * > necessarily an accurate characterization. e.g. there can be a named cluster
- * > group that contains face clusters of pets.
- *
- * The other form of interaction is hiding. The user may hide a single (unnamed)
- * cluster, or they may hide an named cgroup. In both cases, we promote the
- * cluster to a cgroup if needed so that their request to hide gets synced.
- *
- * The user can see both the cgroups and clusters in the UI, but only the
- * cgroups are synced with remote.
- */
+// Only cgroups sync; interacting with a local cluster promotes it.
export interface CGroupUserEntityData {
- /**
- * A name assigned by the user to this cluster group.
- *
- * The client should handle both empty strings and undefined as indicating a
- * cgroup without a name. When the client needs to set this to an <empty>
- * value, which happens when hiding an unnamed cluster, it should it to an
- * empty string. That is, expect `"" | undefined`, but set `""`.
- *
- * [Note: Mark optional for Zod/exactOptionalPropertyTypes]
- *
- * The type is marked as an optional (?) because currently Zod does not
- * differentiate between optionals and undefined-valued properties as
- * required by exactOptionalPropertyTypes.
- */
+ // Empty and undefined both mean unnamed; write empty when clearing.
name?: string | undefined;
- /**
- * An unordered set of clusters that have been assigned to this group.
- *
- * For ease of transportation and persistence this is an array, but it
- * should conceptually be thought of as a set.
- */
+ // These arrays are unordered sets on the wire.
assigned: FaceCluster[];
- /**
- * An unordered set of faces (IDs) that the user has manually marked as not
- * belonging to this group.
- *
- * For ease of transportation and persistence this is an array, but it
- * should conceptually be thought of as a set.
- */
rejectedFaceIDs: string[];
- /**
- * An unordered set of file IDs that the user has manually tagged as
- * belonging to this group.
- *
- * For ease of transportation and persistence this is an array, but it
- * should conceptually be thought of as a set.
- */
manuallyAssigned: number[];
- /**
- * True if this cluster group should be hidden.
- *
- * The user can hide both named cluster groups and single unnamed clusters.
- * If the user hides a single cluster that was offered as a suggestion to
- * them on a client, the client will create a new unnamed cgroup containing
- * it, and set its hidden flag to sync it with remote (so that other clients
- * can also stop showing this cluster).
- */
isHidden: boolean;
- /**
- * The ID of the face that should be used as the cover photo for this
- * cluster group. Optional.
- *
- * This is similar to the [@link displayFaceID}, the difference being:
- *
- * - {@link avatarFaceID} is the face selected by the user.
- *
- * - {@link displayFaceID} is the automatic placeholder, and only comes into
- * effect if the user has not explicitly selected a face.
- *
- * Also, see: [Note: Mark optional for Zod/exactOptionalPropertyTypes]
- */
avatarFaceID?: string | undefined;
- /**
- * True if this cluster group has been pinned by the user.
- */
isPinned?: boolean | undefined;
- /**
- * True if this cluster group should not be surfaced in memories.
- *
- * Desktop does not currently surface memories, but we still need to
- * preserve this flag so that it continues to sync correctly with mobile.
- */
+ // Desktop does not use this yet, but mobile does.
hideFromMemories?: boolean | undefined;
}
-/**
- * A massaged version of {@link CGroup} or a {@link FaceCluster} suitable for
- * being shown in the UI.
- *
- * We transform both both remote cluster groups and local-only face clusters
- * into the same "person" object that can be shown in the UI.
- *
- * The cgroups synced with remote do not directly correspond to "people".
- * CGroups represent both positive and negative feedback (i.e, the user does not
- * wish a particular cluster group to be shown in the UI).
- *
- * So while each person has an underlying cgroups, not all cgroups have a
- * corresponding person.
- *
- * Beyond this semantic difference, there is also data massaging: a
- * {@link Person} has data converted into a format that the UI can directly and
- * efficiently use, as compared to a {@link CGroup}, which is tailored for
- * transmission and storage.
- */
export type Person = (
| { type: "cgroup"; cgroup: CGroup; isHidden: boolean }
| { type: "cluster"; cluster: FaceCluster }
) & {
- /**
- * Nanoid of the underlying cgroup or {@link FaceCluster}.
- */
id: string;
- /**
- * The name of the person.
- *
- * This will only be set for named cgroups.
- */
name: string | undefined;
- /**
- * IDs of the (unique) files in which this face occurs.
- */
fileIDs: number[];
- /**
- * True if the person has been pinned by the user.
- */
isPinned: boolean;
- /**
- * True if the person should be hidden from memories.
- */
hideFromMemories: boolean;
- /**
- * The face that should be used as the "cover" face to represent this
- * {@link Person} in the UI.
- */
displayFaceID: string;
- /**
- * The {@link EnteFile} which contains the display face.
- */
displayFaceFile: EnteFile;
};
-/**
- * A person of type "cgroup".
- */
export type CGroupPerson = Exclude<Person, { type: "cluster" }>;
-/**
- * A person of type "cluster".
- */
export type ClusterPerson = Exclude<Person, { type: "cgroup" }>;
-/**
- * A {@link Person} whose name is not empty.
- */
export type NamedPerson = Person & { name: string };
-/**
- * A face ID annotated with the {@link EnteFile} that contains it.
- *
- * Both these pieces of information are needed for a UI element to show the
- * face.
- */
export interface PreviewableFace {
- /** The ID of the face to display. */
faceID: string;
- /** The {@link EnteFile} which contains this face. */
file: EnteFile;
}
-/**
- * Pre-computed in-memory state for UI that deals with people.
- */
export interface PeopleState {
- /**
- * List of all people.
- *
- * The list is sorted such that named people are first, then the local only
- * unnamed clusters. Within each section, people are sorted by the number of
- * files that they reference.
- */
people: Person[];
- /**
- * List of all people who should be normally shown in the UI.
- *
- * By default, people derived from small, local-only clusters are not
- * surfaced in the UI. Such people will be present in the {@link people}
- * list, but not in the {@link visiblePeople} list. The user can still see
- * these people by clicking on one of the faces they contain from a photo's
- * info view.
- */
visiblePeople: Person[];
- /**
- * faceID => person
- *
- * {@link people}, but indexed by face (ids).
- */
personByFaceID: Map<string, Person>;
}
-/**
- * Construct an in-memory people state using the data present locally, ignoring
- * faces belonging to deleted and hidden files.
- *
- * This function is meant to run after files, cgroups and faces have been synced
- * with remote, and clustering has completed. It uses the current local state to
- * construct an in-memory list of {@link Person}s on which the UI will operate.
- */
export const reconstructPeopleState = async (): Promise<PeopleState> => {
const normalCollectionFiles = await computeNormalCollectionFilesFromSaved();
const fileByID = new Map(normalCollectionFiles.map((f) => [f.id, f]));
- // "Person face"s are faces annotated with their corresponding local files.
- //
- // Note that since we ignore deleted and hidden files, it is possible that
- // there might not be an entry for a particular face in this map even if its
- // file is otherwise existent.
+ // Hidden and deleted files deliberately leave holes in this map.
const personFaceByID = new Map<
string,
{ faceID: string; file: EnteFile; score: number; sortTime: number }
@@ -269,10 +89,6 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
}
}
- // Return annotated "person faces" corresponding to the given face ids,
- // sorting them by the local photo creation date of the file they belong to.
- //
- // Within the same file, sort by the face score.
const personFacesSortedNewestFirst = (faceIDs: string[]) =>
faceIDs
.map((faceID) => personFaceByID.get(faceID))
@@ -283,10 +99,8 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
return bt == at ? b.score - a.score : bt - at;
});
- // Help out tsc.
type Interim = (Person | undefined)[];
- // Convert cgroups to people.
const cgroups = await savedCGroups();
const cgroupPeople: Interim = cgroups.map((cgroup) => {
const { id, data } = cgroup;
@@ -294,13 +108,11 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
let isHidden = data.isHidden;
- // Older versions of the mobile app marked hidden cgroups by setting
- // their name to an empty string.
+ // Older mobile clients encoded hidden cgroups with an empty name.
if (!name) isHidden = true;
let assignedFaceIDs: string[][];
if (data.rejectedFaceIDs.length == 0) {
- // Fast path for when there are no rejected faces.
assignedFaceIDs = assigned.map(({ faces }) => faces);
} else {
const rejectedFaceIDs = new Set(data.rejectedFaceIDs);
@@ -309,24 +121,17 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
);
}
- // Person faces from all the clusters assigned to this cgroup, sorted by
- // recency (then score).
const faces = personFacesSortedNewestFirst(assignedFaceIDs.flat());
- // Ignore this cgroup if we don't have visible faces left in it.
const mostRecentFace = faces[0];
if (!mostRecentFace) return undefined;
- // IDs of the files containing this face, plus any files manually
- // associated with this person.
const fileIDsSet = new Set(faces.map((f) => f.file.id));
for (const fileID of data.manuallyAssigned) {
- // Only include normal (non-hidden, non-deleted) files.
if (fileByID.has(fileID)) fileIDsSet.add(fileID);
}
const fileIDs = [...fileIDsSet];
- // Avatar face ID, or the highest scoring face.
let avatarFile: EnteFile | undefined;
const avatarFaceID = resolvedAvatarFaceID(data.avatarFaceID);
if (avatarFaceID) {
@@ -361,12 +166,10 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
};
});
- // Convert local-only clusters to people.
const localClusters = await savedFaceClusters();
const clusterPeople: Interim = localClusters.map((cluster) => {
const faces = personFacesSortedNewestFirst(cluster.faces);
- // Ignore this cluster if we don't have visible faces left in it.
const mostRecentFace = faces[0];
if (!mostRecentFace) return undefined;
@@ -399,23 +202,17 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
const visiblePeople = people.filter((p) => {
switch (p.type) {
case "cgroup":
- // Hidden cgroups are clusters specifically marked so as to not
- // be shown in the UI. The user can still see them from within
- // file info if they wish.
if (p.isHidden) return false;
break;
case "cluster":
- // Ignore local only clusters with too few visible faces.
if (p.cluster.faces.length < 10) return false;
break;
}
- // Show it.
return true;
});
- // Reverse map for easy lookup.
const personByFaceID = new Map<string, Person>();
for (const person of people) {
const faceIDs =
@@ -430,19 +227,10 @@ export const reconstructPeopleState = async (): Promise<PeopleState> => {
return { people, visiblePeople, personByFaceID };
};
-/**
- * Older versions of the mobile app set the avatarFileID as the avatarFaceID.
- * Use the format of the string to detect such cases, and as a workaround,
- * ignore the avatarID in such cases.
- */
+// Older mobile clients stored avatarFileID in this field.
const resolvedAvatarFaceID = (avatarFaceID: string | undefined) =>
avatarFaceID?.split("_").length == 1 ? undefined : avatarFaceID;
-/**
- * Return only those from amongst {@link people} that have a name defined.
- *
- * @param people List of all people, named and unnamed.
- */
export const filterNamedPeople = (people: Person[]): NamedPerson[] => {
const namedPeople: NamedPerson[] = [];
for (const person of people) {
@@ -455,41 +243,14 @@ export const filterNamedPeople = (people: Person[]): NamedPerson[] => {
};
export type PreviewableCluster = FaceCluster & {
- /**
- * A list of up to 3 "preview" faces for the cluster, each annotated with
- * the corresponding {@link EnteFile} that contains them.
- */
previewFaces: PreviewableFace[];
};
export interface PersonSuggestionsAndChoices {
- /**
- * Previously saved choices.
- *
- * These are clusters (sorted by size) that the user had previously assigned
- * to or explicitly rejected from the person under consideration.
- *
- * The {@link assigned} flag will true for the entries that correspond to
- * assigned clusters, and false for those that the user had rejected.
- *
- * This array is guaranteed to be non-empty, and it is guaranteed that the
- * first item is a merged cluster (i.e. a cluster for which assigned is
- * true), even if there exists an ignored cluster with a larger size. The
- * rest of the entries are intermixed and sorted by size normally.
- *
- * For convenience of the UI, the first entry will have also have the
- * {@link fixed} flag set.
- */
choices: (PreviewableCluster & { fixed?: boolean; assigned: boolean })[];
- /**
- * New suggestions to offer to the user.
- */
suggestions: PreviewableCluster[];
}
-/**
- * Returns suggestions and existing choices for the given person.
- */
export const _suggestionsAndChoicesForPerson = async (
person: CGroupPerson,
currentUserID: number,
@@ -524,7 +285,7 @@ export const _suggestionsAndChoicesForPerson = async (
.flat()
.filter((e) => !!e);
- // Randomly sample faces to limit the O(n^2) cost.
+ // Bound the quadratic pairwise comparison cost.
const sampledPersonEmbeddings = randomSample(personFaceEmbeddings, 50);
const strictMedianSimilarityThreshold = 0.48;
@@ -536,10 +297,7 @@ export const _suggestionsAndChoicesForPerson = async (
for (const cluster of localClusters) {
const { id, faces } = cluster;
- // User has explicitly asked us to ignore this cluster. Add it to the
- // list of rejected clusters that we return to the UI for listing out.
- // Keep this check first so that we pick these up even if we get e.g.
- // singleton clusters from remote.
+ // Check rejection first so remote singleton rejections remain visible.
if (rejectedClusterIDs.has(id)) {
rejectedClusters.push(cluster);
continue;
@@ -561,7 +319,6 @@ export const _suggestionsAndChoicesForPerson = async (
.map((id) => embeddingByFaceID.get(id))
.filter((e) => !!e);
- // Sort all cosine similarities pairs, and consider their median.
const csims: number[] = [];
for (const other of sampledOtherEmbeddings) {
for (const embedding of sampledPersonEmbeddings) {
@@ -572,10 +329,10 @@ export const _suggestionsAndChoicesForPerson = async (
if (csims.length == 0) continue;
+ // Median similarity dampens a few misleading face pairs.
const medianSim = csims[Math.floor(csims.length / 2)]!;
clustersAndSimilarity.push([cluster, medianSim]);
}
- // Sort suggestions by the (median) cosine similarity.
clustersAndSimilarity.sort(([, a], [, b]) => b - a);
return clustersAndSimilarity;
};
@@ -594,8 +351,6 @@ export const _suggestionsAndChoicesForPerson = async (
)
.map(([cluster]) => cluster);
- // Keep singleton suggestions as a last resort to minimize regressions while
- // still reducing "no suggestions" outcomes.
const multiFaceCandidateClustersAndSimilarity =
scoreClustersByMedianSimilarity(multiFaceClusters);
let suggestionMode = "strict_non_singleton";
@@ -610,6 +365,7 @@ export const _suggestionsAndChoicesForPerson = async (
minMedianSimilarity: relaxedMedianSimilarityThreshold,
});
}
+ // Singleton clusters are the final fallback.
if (suggestedClusters.length == 0) {
suggestionMode = "strict_with_singletons";
const singletonCandidateClustersAndSimilarity =
@@ -620,8 +376,6 @@ export const _suggestionsAndChoicesForPerson = async (
});
}
- // Annotate the clusters with the information that the UI needs to show its
- // preview faces.
const normalCollectionFiles =
await computeNormalCollectionFilesFromSaved(currentUserID);
const fileByID = new Map(normalCollectionFiles.map((f) => [f.id, f]));
@@ -637,8 +391,6 @@ export const _suggestionsAndChoicesForPerson = async (
const file = fileByID.get(fileID);
if (!file) {
- // This might be a hidden/trash file, and it is thus not
- // appropriate to use it as a preview file anyway.
continue;
}
@@ -670,16 +422,12 @@ export const _suggestionsAndChoicesForPerson = async (
assigned: false,
}));
- // Ensure that the first item in the choices is not an ignored one, even if
- // that is what we'd have ended up with if we sorted by size.
-
const firstChoice = { ...assignedChoices[0]!, fixed: true };
const restChoices = assignedChoices.slice(1).concat(rejectedChoices);
sortBySize(restChoices);
const choices = [firstChoice, ...restChoices];
- // Limit to the number of suggestions shown in a single go.
const suggestions = toPreviewableList(suggestedClusters.slice(0, 80));
log.info(
@@ -689,39 +437,11 @@ export const _suggestionsAndChoicesForPerson = async (
return { choices, suggestions };
};
-/**
- * A map specifying the changes to make when the user presses the save button on
- * the people suggestions dialog.
- *
- * Each entry is a (clusterID, update) pair.
- *
- * * Clusters with "assign" should be assigned to the cgroup,
- * * Clusters with "rejectSuggestion" should be rejected from the cgroup
- * locally. These correspond to suggestions which the user did not accept.
- * * Clusters with "rejectSavedChoice" should be rejected from the cgroup both
- * locally and on remote. These correspond to saved choices which the user
- * went on to explicitly reject.
- * * Clusters with "reset" should be reset - i.e. should be removed from both
- * the assigned and rejected choices associated with the cgroup (if needed).
- */
export type PersonSuggestionUpdates = Map<
string,
"assign" | "rejectSuggestion" | "rejectSavedChoice" | "reset"
>;
-/**
- * Implementation for the "save" action on the SuggestionsDialog.
- *
- * This function modifies remote and local state to reflect the given
- * {@link updates} for {@link cgroup}.
- *
- * @param cgroup The cgroup that we want to update.
- *
- * @param updates The changes to make. See {@link PersonSuggestionUpdates}.
- *
- * @param masterKey The user's masterKey (as a base64 string), which is is used
- * to encrypt and decrypt the entity key associated with cgroups.
- */
export const _applyPersonSuggestionUpdates = async (
cgroup: CGroup,
updates: PersonSuggestionUpdates,
@@ -739,15 +459,12 @@ export const _applyPersonSuggestionUpdates = async (
const clusterWithID = (clusterID: string) =>
localClusters.find((c) => c.id == clusterID)!;
- // Add cluster with `clusterID` to the list of assigned clusters.
const assign = (clusterID: string) => {
const cluster = clusterWithID(clusterID);
assignedClusters.push(cluster);
assignUpdateCount += 1;
};
- // Remove cluster with `clusterID` from the list of assigned clusters (if
- // needed).
const unassignIfNeeded = (clusterID: string) => {
if (assignedClusters.find(({ id }) => id == clusterID)) {
const [updatedAssignedClusters, cluster] = assignedClusters.reduce<
@@ -763,27 +480,21 @@ export const _applyPersonSuggestionUpdates = async (
assignedClusters = updatedAssignedClusters;
assignUpdateCount += 1;
- // Prior to this, this cluster was not saved locally since it was
- // part of the remote data. Since we're removing it from the remote
- // state, add it to the local state instead so that the user can see
- // it in their saved choices (local only).
+ // Assigned clusters came from remote; restore them locally first.
localClusters.push(cluster!);
}
};
- // Add `clusterID` to the list of rejected clusters locally.
const rejectClusterLocal = (clusterID: string) => {
rejectedClusterIDs.push(clusterID);
rejectUpdateCount += 1;
};
- // Mark the faces in `clusterID` as rejected on remote.
const rejectFacesRemote = (clusterID: string) => {
const cluster = clusterWithID(clusterID);
newlyRejectedFaceIDs = newlyRejectedFaceIDs.concat(cluster.faces);
};
- // Remove `clusterID` from the list of rejected clusters (if needed).
const unrejectIfNeeded = (clusterID: string) => {
if (rejectedClusterIDs.includes(clusterID)) {
rejectedClusterIDs = rejectedClusterIDs.filter(
diff --git a/web/packages/new/photos/services/ml/worker.ts b/web/packages/new/photos/services/ml/worker.ts
index 881cafbc07..cc47ddcea8 100644
--- a/web/packages/new/photos/services/ml/worker.ts
+++ b/web/packages/new/photos/services/ml/worker.ts
@@ -56,99 +56,32 @@ import {
import { _suggestionsAndChoicesForPerson, type CGroupPerson } from "./people";
import type { CLIPMatches, MLWorkerDelegate } from "./worker-types";
-/**
- * A rough hint at what the worker is up to.
- *
- * - "init": Worker has been created but hasn't done anything yet.
- * - "idle": Not doing anything
- * - "tick": Transitioning to a new state
- * - "indexing": Indexing
- * - "fetching": A subset of indexing
- *
- * During indexing, the state is set to "fetching" whenever remote provided us
- * data for more than 50% of the files that we requested from it in the last
- * fetch during indexing.
- */
export type WorkerState = "init" | "idle" | "tick" | "indexing" | "fetching";
-const idleDurationStart = 5; /* 5 seconds */
-const idleDurationMax = 16 * 60; /* 16 minutes */
+const idleDurationStart = 5;
+const idleDurationMax = 16 * 60;
interface IndexableItem {
- /**
- * The {@link EnteFile} to (potentially) index.
- */
file: EnteFile;
- /**
- * If the file was uploaded from the current client, then its contents.
- */
processableUploadItem: ProcessableUploadItem | undefined;
- /**
- * The existing ML data (if any) on remote corresponding to this file.
- */
remoteMLData: RemoteMLData | undefined;
}
-/**
- * Run operations related to machine learning (e.g. indexing) in a Web Worker.
- *
- * This is a normal class that is however exposed (via comlink) as a proxy
- * running inside a Web Worker. This way, we do not bother the main thread with
- * tasks that might degrade interactivity.
- *
- * Conceptually, the MLWorker state machine is as follows:
- *
- * ext. event state then state
- * ------------- --------------- --------------
- * sync -> "backfillq" -> "idle"
- * upload -> "liveq" -> "idle"
- * idleTimeout -> "backfillq" -> "idle"
- *
- * where:
- *
- * - "liveq": indexing items that are being uploaded,
- * - "backfillq": index unindexed items otherwise.
- * - "idle": in between state transitions.
- *
- * In addition, MLWorker can also be invoked for interactive tasks: in
- * particular, for finding the closest CLIP match when the user does a search.
- */
export class MLWorker {
- /** The last known state of the worker. */
public state: WorkerState = "init";
- /** If the worker is currently clustering, then its last known progress. */
public clusteringProgress: ClusteringProgress | undefined;
private electron: ElectronMLWorker | undefined;
private delegate: MLWorkerDelegate | undefined;
private liveQ: IndexableItem[] = [];
private idleTimeout: ReturnType<typeof setTimeout> | undefined;
- private idleDuration = idleDurationStart; /* unit: seconds */
- /** Settlers for pending promises returned from calls to {@link index}. */
+ private idleDuration = idleDurationStart;
private onNextIdles: {
resolve: (count: number) => void;
reject: (e: Error) => void;
}[] = [];
- /**
- * Number of items processed since the last time {@link onNextIdles} was
- * drained.
- */
private countSinceLastIdle = 0;
- /**
- * Initialize a new {@link MLWorker}.
- *
- * This is conceptually the constructor, however it is easier to have this
- * as a separate function to avoid complicating the comlink types further.
- *
- * @param port A {@link MessagePort} that allows us to communicate with an
- * Electron utility process running in the Node.js layer of our desktop app,
- * exposing an object that conforms to the {@link ElectronMLWorker}
- * interface.
- *
- * @param delegate The {@link MLWorkerDelegate} the worker can use to inform
- * the main thread of interesting events.
- */
init(port: MessagePort, delegate: MLWorkerDelegate) {
this.electron = wrap<ElectronMLWorker>(port);
this.delegate = delegate;
@@ -157,16 +90,8 @@ export class MLWorker {
});
}
- /**
- * Called when the port to the ML utility process closes, which happens if
- * the utility process exits (e.g. if it crashes).
- *
- * Reject any pending promises returned by {@link index} so that a sync
- * awaiting us doesn't hang forever, then inform the main thread, which
- * will discard us. Anything else in flight dies with us; the next sync
- * will retry with a new worker.
- */
private electronPortDidClose() {
+ // Reject waiters or the main sync would hang forever.
const onNextIdles = this.onNextIdles;
this.onNextIdles = [];
onNextIdles.forEach(({ reject }) =>
@@ -175,18 +100,6 @@ export class MLWorker {
this.delegate?.workerDidLoseElectronPort();
}
- /**
- * Start backfilling if needed, and return after there are no more items
- * remaining to backfill.
- *
- * During a backfill, we first attempt to fetch ML data for files which
- * don't have that data locally. If on fetching we find what we need, we
- * save it locally. Otherwise we index them.
- *
- * @return The count of items processed since the last last time we were
- * idle. The returned promise rejects if the port to the ML utility process
- * closes while we're indexing.
- */
index() {
if (_blockingMLInitError) return Promise.resolve(0);
@@ -197,33 +110,21 @@ export class MLWorker {
return nextIdle;
}
- /** Invoked in response to external events. */
private wakeUp() {
if (this.state == "init" || this.state == "idle") {
- // We are currently paused. Get back to work.
if (this.idleTimeout) clearTimeout(this.idleTimeout);
this.idleTimeout = undefined;
- // Change state so that multiple calls to `wakeUp` don't cause
- // multiple calls to `tick`.
+ // Claim the transition before another wakeUp can schedule a tick.
this.state = "tick";
- // Enqueue a tick.
void this.tick();
} else {
- // In the middle of a task. Do nothing, `this.tick` will
- // automatically be invoked when the current task finishes.
+ // The current tick schedules the next one.
}
}
- /**
- * Called when a file is uploaded from the current client.
- *
- * This is a great opportunity to index since we already have the file with
- * us and won't need to download the file from remote.
- */
onUpload(file: EnteFile, processableUploadItem: ProcessableUploadItem) {
if (_blockingMLInitError) return;
- // Add the recently uploaded file to the live indexing queue.
this.liveQ.push({
file,
processableUploadItem,
@@ -232,9 +133,6 @@ export class MLWorker {
this.wakeUp();
}
- /**
- * Find {@link CLIPMatches} for a given normalized {@link searchPhrase}.
- */
async clipMatches(searchPhrase: string): Promise<CLIPMatches | undefined> {
return _clipMatches(searchPhrase, this.electron!);
}
@@ -254,26 +152,17 @@ export class MLWorker {
const liveQ = this.liveQ;
this.liveQ = [];
- // Retain the previous state if it was one of the indexing states. This
- // prevents jumping between "fetching" and "indexing" being shown in the
- // UI during the initial load.
if (this.state != "fetching" && this.state != "indexing")
this.state = "indexing";
- // Use the liveQ if present, otherwise get the next batch to backfill.
const items = liveQ.length
? liveQ
: await this.backfillQ().catch((e: unknown) => {
- // Ignore the error (e.g. a network failure) when determining
- // the items to backfill, and return an empty items array so
- // that the next retry happens after an exponential backoff.
log.warn("Ignoring error when determining backfillQ", e);
return [];
});
- // If there is items remaining,
if (items.length > 0) {
- // Index them.
const { indexedCount, blockingInitError } = await indexNextBatch(
items,
this.electron!,
@@ -286,34 +175,18 @@ export class MLWorker {
this.countSinceLastIdle += items.length;
if (indexedCount > 0) {
- // We made some progress, so there are no complete blockers
- // (e.g. network being offline). Reset the idle duration and
- // move on to the next batch (if any).
this.idleDuration = idleDurationStart;
- // And tick again.
scheduleTick();
return;
}
}
- // We come here in three scenarios - either there is nothing left to do,
- // or we cannot currently do it (e.g. user is offline), or we
- // encountered failures during indexing.
- //
- // Failures are not really expected, so something unexpected might be
- // going on, or remote might be having issues.
- //
- // So in all cases, we pause for exponentially longer durations of time
- // (limited to some maximum).
-
this.state = "idle";
this.idleDuration = Math.min(this.idleDuration * 2, idleDurationMax);
this.idleTimeout = setTimeout(scheduleTick, this.idleDuration * 1000);
this.delegate?.workerDidUpdateStatus();
- // Release the native ML sessions while we're idling so that the
- // utility process doesn't hold on to the model memory. They get
- // recreated transparently on the next analysis.
+ // Native sessions retain the model memory while idle.
void this.electron?.releaseMLRuntime().catch((e: unknown) => {
log.warn("Failed to release the native ML runtime", e);
});
@@ -321,7 +194,6 @@ export class MLWorker {
this.resolvePendingIndexRequests();
}
- /** Stop indexing until this web worker (and its utility process) is replaced. */
private suspendForMLInitError(error: MLAnalyzeError) {
log.error(
"Suspending ML indexing because the native runtime failed to initialize",
@@ -334,7 +206,6 @@ export class MLWorker {
this.resolvePendingIndexRequests();
}
- /** Resolve callers waiting for the worker to next become idle. */
private resolvePendingIndexRequests() {
const onNextIdles = this.onNextIdles;
const countSinceLastIdle = this.countSinceLastIdle;
@@ -342,33 +213,22 @@ export class MLWorker {
this.countSinceLastIdle = 0;
onNextIdles.forEach(({ resolve }) => resolve(countSinceLastIdle));
- // If no one was waiting, then let the main thread know via a different
- // channel so that it can update the clusters and people.
if (onNextIdles.length == 0 && countSinceLastIdle > 0) {
this.delegate?.workerDidUnawaitedIndex();
}
}
- /** Return the next batch of items to backfill (if any). */
private async backfillQ() {
- // Find files that our local DB thinks need syncing.
const fileByID = await syncWithLocalFilesAndGetFilesToIndex(200);
if (!fileByID.size) return [];
- // Fetch their existing ML data (if any).
const mlDataByID = await fetchMLData(fileByID);
- // If the number of files for which remote gave us data is more than 50%
- // of what we asked of it, assume we are "fetching", not "indexing".
- // This is a heuristic to try and show a better indexing state in the UI
- // (so that the user does not think that their files are being
- // unnecessarily reindexed).
if (this.state != "indexing" && this.state != "fetching")
assertionFailed(`Unexpected state ${this.state}`);
this.state =
mlDataByID.size * 2 > fileByID.size ? "fetching" : "indexing";
- // Return files after annotating them with their existing ML data.
return Array.from(fileByID, ([id, file]) => ({
file,
processableUploadItem: undefined,
@@ -376,19 +236,8 @@ export class MLWorker {
}));
}
- /**
- * Run face clustering on all faces, and update both local and remote state
- * as appropriate.
- *
- * This should only be invoked when the face indexing (including syncing
- * with remote) is complete so that we cluster the latest set of faces, and
- * after we have fetched the latest cgroups from remote (so that we do no
- * overwrite any remote updates).
- *
- * @param masterKey The user's master key (as a base64 string), required for
- * updating remote cgroups if needed.
- */
async clusterFaces(masterKey: string, reason: ClusterFacesReason) {
+ // Face indexing must be complete and cgroups current before this runs.
const { clusters, modifiedClusterIDs } = await _clusterFaces(
await savedFaceIndexes(),
await savedCollectionFiles(),
@@ -404,9 +253,6 @@ export class MLWorker {
this.delegate?.workerDidUpdateStatus();
}
- /**
- * Return suggestions and choices for the given cgroup {@link person}.
- */
async suggestionsAndChoicesForPerson(
person: CGroupPerson,
currentUserID: number,
@@ -419,36 +265,25 @@ expose(MLWorker);
logUnhandledErrorsAndRejectionsInWorker();
-/**
- * Index the given batch of items.
- *
- * @returns the number of indexed items and any process-blocking init error.
- */
const indexNextBatch = async (
items: IndexableItem[],
electron: ElectronMLWorker,
delegate: MLWorkerDelegate | undefined,
) => {
- // Don't try to index if we wouldn't be able to upload them anyway. The
- // liveQ has already been drained, but that's fine, it'll be rare that we
- // were able to upload just a bit ago but don't have network now.
if (!self.navigator.onLine) {
log.info("Skipping ML indexing since we are not online");
return { indexedCount: 0 };
}
- // Keep track if any of the items failed.
let failureCount = 0;
- // Index up to 4 items simultaneously.
+ // Parallelize fetch/decrypt, while native inference remains serialized below.
const tasks = new Array<Promise<void> | undefined>(4).fill(undefined);
let i = 0;
while (i < items.length && !_blockingMLInitError) {
for (let j = 0; j < tasks.length; j++) {
if (i < items.length && !tasks[j]) {
- // Use an IIFE to capture the value of j at the time of
- // invocation.
tasks[j] = ((item: IndexableItem, j: number) =>
index(item, electron)
.then(() => {
@@ -466,22 +301,15 @@ const indexNextBatch = async (
}
}
- // Wait for at least one to complete (the other runners continue running
- // even if one promise reaches the finish line).
await Promise.race(tasks.filter((task) => task !== undefined));
- // Let the main thread now we're doing something.
delegate?.workerDidUpdateStatus();
- // Let us drain the microtask queue. This also gives a chance for other
- // interactive tasks like `clipMatches` to run.
await wait(0);
}
- // Wait for the pending tasks to drain out.
await Promise.all(tasks.filter((task) => task !== undefined));
- // Clear any cached CLIP indexes, since now we might have new ones.
clearCachedCLIPIndexes();
const attemptedCount = i;
@@ -496,17 +324,6 @@ const indexNextBatch = async (
return { indexedCount, blockingInitError: _blockingMLInitError };
};
-/**
- * Sync face DB with the local (and potentially indexable) files that we know
- * about. Then return the next {@link count} files that still need to be
- * indexed.
- *
- * When returning from amongst pending files, prefer the most recent ones first.
- *
- * For specifics of what a "sync" entails, see {@link updateAssumingLocalFiles}.
- *
- * @param count Limit the resulting list of indexable files to {@link count}.
- */
const syncWithLocalFilesAndGetFilesToIndex = async (
count: number,
): Promise<Map<number, EnteFile>> => {
@@ -522,51 +339,7 @@ const syncWithLocalFilesAndGetFilesToIndex = async (
return new Map(fileIDsToIndex.map((id) => [id, fileByID.get(id)!]));
};
-/**
- * The maximum size (in bytes) of files that we will index.
- *
- * The same limit is used by the mobile app.
- */
-const maxIndexableFileSize = 100 * 1000 * 1000; /* 100 MB */
-
-/**
- * Index file, save the persist the results locally, and put them on remote.
- *
- * Indexing a file involves computing its various ML embeddings: faces and CLIP.
- * Since we have the original file in memory, we also save the face crops.
- *
- * [Note: Transient and permanent indexing failures]
- *
- * We mark indexing for a file as having failed only if there is a good chance
- * that the indexing failed because of some inherent issue with that particular
- * file, and not if there were generic failures (like when trying to save the
- * indexes to remote).
- *
- * When we mark it as failed, then a flag is persisted corresponding to this
- * file in the ML DB so that it won't get reindexed in future runs. This are
- * thus considered as permanent failures.
- *
- * > We might retry these in future versions if we identify reasons for indexing
- * > to fail (it ideally shouldn't) and rectify them.
- *
- * On the other hand, saving the face index to remote might fail for transient
- * issues (network issues, or remote having hiccups). We don't mark a file as
- * failed permanently in such cases, so that it gets retried at some point.
- * These are considered as transient failures.
- *
- * However, it is vary hard to pre-emptively enumerate all possible failure
- * modes, and there is a the possibility of some non-transient failure getting
- * classified as a transient failure and causing the client to try and index the
- * same file again and again, when in fact there is a issue specific to that
- * file which is preventing the index from being saved. What exactly? We don't
- * know, but the possibility exists.
- *
- * To reduce the chances of this happening, we treat HTTP 4xx responses as
- * permanent failures too - there are no known cases where a client retrying a
- * 4xx response would work, and there are expected (but rare) cases where a
- * client might get a non-retriable 4xx (e.g. if the file has over ~700 faces,
- * then remote will return a 413 Request Entity Too Large).
- */
+const maxIndexableFileSize = 100 * 1000 * 1000;
const index = async (
{ file, processableUploadItem, remoteMLData }: IndexableItem,
electron: ElectronMLWorker,
@@ -574,12 +347,6 @@ const index = async (
const f = fileLogID(file);
const fileID = file.id;
- // Massage the existing data (if any) that we got from remote to the form
- // that the rest of this function operates on.
- //
- // Discard any existing data that is made by an older indexing pipelines.
- // See: [Note: Embedding versions]
-
const existingRemoteFaceIndex = remoteMLData?.parsed?.face;
const existingRemoteCLIPIndex = remoteMLData?.parsed?.clip;
@@ -588,8 +355,6 @@ const index = async (
existingRemoteFaceIndex &&
existingRemoteFaceIndex.version >= faceIndexingVersion
) {
- // Destructure the data we got from remote so that we only retain the
- // fields we're interested in the object that gets put into indexed db.
const { width, height, faces } = existingRemoteFaceIndex;
existingFaceIndex = { width, height, faces };
}
@@ -603,9 +368,6 @@ const index = async (
existingCLIPIndex = { embedding };
}
- // If we already have all the ML data types then just update our local db
- // and return.
-
if (existingFaceIndex && existingCLIPIndex) {
await saveIndexes(
{ fileID, ...existingFaceIndex },
@@ -614,12 +376,9 @@ const index = async (
return;
}
- // There is at least one ML data type that still needs to be indexed.
-
let source: IndexableImageSource;
try {
- // Videos are indexed using their thumbnails, so the size of the video
- // file itself does not matter.
+ // Videos use thumbnails, so their original file size is irrelevant.
if (
file.metadata.fileType != FileType.video &&
(file.info?.fileSize ?? 0) > maxIndexableFileSize
@@ -634,9 +393,7 @@ const index = async (
electron,
);
} catch (e) {
- // Network errors are transient and shouldn't be marked.
- //
- // See: [Note: Transient and permanent indexing failures]
+ // Network failures retry; failures inherent to the file do not.
if (!isNetworkDownloadError(e)) await markIndexingFailed(fileID);
throw e;
}
@@ -655,10 +412,7 @@ const index = async (
electron,
);
} catch (e) {
- // Only failures inherent to the image (including the JPEG conversion
- // fallback below) are permanent. Runtime and infrastructure failures
- // should be retried after the underlying issue is resolved.
- // See: [Note: Transient and permanent indexing failures]
+ // Runtime failures retry after repair; image failures are permanent.
if (isMLImageError(e)) await markIndexingFailed(fileID);
throw e;
}
@@ -695,13 +449,7 @@ const index = async (
...clipIndex,
};
- // Perform an "upsert" by using the existing raw data we got from the
- // remote as the base, and inserting or overwriting only the parts we
- // actually (re)indexed. Preserving the raw entry for a kept
- // face/clip retains any inner keys that the current client's Zod
- // schema doesn't know about (e.g. a `flags` bitmask set by a
- // different client). See: [Note: Preserve unknown ML data fields].
-
+ // Preserve fields added by newer clients when upserting known indexes.
const existingRawMLData = remoteMLData?.raw ?? {};
const rawMLData: RawRemoteMLData = {
...existingRawMLData,
@@ -715,11 +463,8 @@ const index = async (
const lastUpdatedAt = remoteMLData?.updatedAt ?? 0;
await putMLData(file, rawMLData, lastUpdatedAt);
} catch (e) {
- // See: [Note: Transient and permanent indexing failures]
+ // 4xx is permanent except 409, which means the data already exists.
if (isHTTP4xxError(e)) {
- // 409 Conflict indicates that we tried overwriting existing
- // mldata. Don't mark it as a failure, the file has already been
- // processed.
if (!isHTTPErrorWithStatus(e, 409)) {
await markIndexingFailed(fileID);
}
@@ -729,39 +474,18 @@ const index = async (
await saveIndexes({ fileID, ...faceIndex }, { fileID, ...clipIndex });
- // This step, saving face crops, is conceptually not part of the indexing
- // pipeline; we just do it here since the analysis has already generated
- // the crops for us from its decode of the original.
+ // Crop caching is best-effort and must not invalidate a saved index.
if (runFaces && result.faceCrops) {
try {
await saveFaceCropBlobs(result.faceCrops, faceIndex);
} catch (e) {
- // Ignore errors that happen during this since it does not
- // impact the generated face index.
log.error(`Failed to save face crops for ${f}`, e);
}
}
};
-/**
- * `true` if the pet recognition models should also run while indexing.
- *
- * Pet recognition is still under development and not yet enabled anywhere.
- * When it ships, this gate should mirror the mobile one (mobile's
- * `flagService.petEnabled` is derived from the remote `internalUser` flag),
- * and the pet results in the analysis response, currently ignored, will need
- * to be persisted.
- */
const petsIndexingEnabled = false;
-/**
- * Run the native ML pipeline on the given image source.
- *
- * The native side decodes all common formats (including HEIC, JXL and TIFF)
- * by itself, but not some rarer ones (e.g. camera RAW). For formats which the
- * app handles by converting to JPEG, retry the analysis with the converted
- * JPEG if the native decode reports a failure.
- */
const analyzeImageWithConversionFallback = async (
file: EnteFile,
source: IndexableImageSource,
@@ -779,6 +503,7 @@ const analyzeImageWithConversionFallback = async (
try {
return await enqueueAnalyzeImage(electron, { ...request, ...source });
} catch (e) {
+ // Native decode failures for rare formats get one JPEG fallback.
const ext = lowercaseExtension(fileFileName(file));
if (!isMLDecodeError(e) || !ext || !needsJPEGConversion(ext)) throw e;
@@ -803,11 +528,9 @@ const analyzeImageWithConversionFallback = async (
}
};
-/** `true` for a permanent failure inherent to the image being analyzed. */
const isMLImageError = (e: unknown): e is MLAnalyzeError =>
e instanceof MLAnalyzeError && e.kind == "image";
-/** `true` specifically for the Rust image decoder failure that permits fallback. */
const isMLDecodeError = (e: unknown) =>
isMLImageError(e) && e.message.startsWith("Decode: ");
@@ -824,18 +547,9 @@ class MLAnalyzeError extends Error {
}
}
-/**
- * A promise queue serializing calls to {@link ElectronMLWorker.analyzeImage}.
- *
- * We process multiple files in parallel so that the fetch (and decrypt) of
- * subsequent items can proceed while one is being analyzed, but keep only a
- * single native inference outstanding at a time: the native model sessions
- * serialize anyway, and queueing on our end avoids tying up worker threads in
- * the utility process.
- */
+// Native model sessions serialize anyway; keep only one inference outstanding.
let _analyzeImageQueue: Promise<unknown> = Promise.resolve();
-/** The native addon is loaded only once, so this error cannot recover here. */
let _blockingMLInitError: MLAnalyzeError | undefined;
const enqueueAnalyzeImage = (
@@ -856,14 +570,7 @@ const enqueueAnalyzeImage = (
return result;
};
-/**
- * Convert the face related parts of an analysis result into the
- * {@link FaceIndex} shape that we persist and upload.
- *
- * The coordinates in the result are already relative (normalized 0-1), and
- * the faceIDs already have the format that the (legacy) web pipeline used, so
- * this is a mechanical reshaping.
- */
+// Convert native typed arrays before serializing either index.
const faceIndexFromAnalysisResult = (
result: MLWorkerAnalyzeImageResult,
): FaceIndex => {
@@ -893,20 +600,11 @@ const faceIndexFromAnalysisResult = (
},
score: face.detection.score,
blur: face.blurValue,
- // Keep persisted and remote indexes as ordinary arrays. The
- // native/IPC boundary uses Float32Array to avoid widening and an
- // extra allocation, but JSON does not serialize typed arrays as
- // arrays.
embedding: Array.from(face.embedding),
})),
};
};
-/**
- * Extract the CLIP image embedding from an analysis result.
- *
- * The embedding produced by the native pipeline is already normalized.
- */
const clipIndexFromAnalysisResult = (
result: MLWorkerAnalyzeImageResult,
): CLIPIndex => {
diff --git a/web/packages/new/photos/services/photos-fdb.ts b/web/packages/new/photos/services/photos-fdb.ts
index 2324558aa7..1d49f89aa5 100644
--- a/web/packages/new/photos/services/photos-fdb.ts
+++ b/web/packages/new/photos/services/photos-fdb.ts
@@ -1,7 +1,3 @@
-/**
- * @file Photos app specific files DB. See: [Note: Files DB].
- */
-
import {
LocalCollections,
LocalEnteFile,
@@ -14,190 +10,64 @@ import type { EnteFile } from "ente-media/file";
import { z } from "zod";
import type { TrashItem } from "./trash";
-/**
- * Return all collections present in our local database.
- *
- * This includes both normal (non-hidden) and hidden collections.
- *
- * Use {@link saveCollections} to update the database.
- */
export const savedCollections = async (): Promise<Collection[]> =>
LocalCollections.parse((await localForage.getItem("collections")) ?? []);
-/**
- * Replace the list of collections stored in our local database.
- *
- * This is the setter corresponding to {@link savedCollections}.
- *
- * This updates the underlying storage of both normal (non-hidden) and hidden
- * collections (the split between normal and hidden is not at the database level
- * but is a filter when they are accessed).
- */
export const saveCollections = async (collections: Collection[]) => {
await localForage.setItem("collections", collections);
};
-/**
- * Return the locally persisted {@link updationTime} of the latest collection we
- * have pulled from remote.
- *
- * Use {@link saveCollectionsUpdationTime} to update the saved value.
- */
export const savedCollectionsUpdationTime = async () =>
LocalTimestamp.parse(await localForage.getItem("collection-updation-time"));
-/**
- * Update the locally persisted timestamp that will be returned by subsequent
- * calls to {@link savedCollectionsUpdationTime}.
- */
export const saveCollectionsUpdationTime = async (time: number) => {
await localForage.setItem("collection-updation-time", time);
};
-const TrashItemCollectionKey = z.object({
- /**
- * Collection ID.
- */
- id: z.number(),
- /**
- * Decrypted collection key.
- */
- key: z.string(),
-});
+const TrashItemCollectionKey = z.object({ id: z.number(), key: z.string() });
const TrashItemCollectionKeys = TrashItemCollectionKey.array();
export type TrashItemCollectionKey = z.infer<typeof TrashItemCollectionKey>;
-/**
- * Return keys of collections (including potentially deleted ones) referred to
- * by trash items present in our local database.
- *
- * Use {@link saveTrashItemCollectionKeys} to update the database.
- *
- * [Note: Trash item collection keys]
- *
- * Trash items are erstwhile files, and like collection files, they need a
- * collection key to decrypt them.
- *
- * However, it is possible that the collection which contained the file was also
- * deleted. Such deleted collections will not be present in the list returned by
- * {@link savedCollections}.
- *
- * So to still be able to access the collection keys in order to process the
- * trash item, we separately save a list of {collectionID, collectionKey} pairs.
- *
- * - This list contains only collectionsIDs for which there is a corresponding
- * local trash item.
- *
- * - During each trash sync, this list is seeded using {@link savedCollections}.
- * Then, whenever we encounter a collection which is not present locally
- * (since it might've been deleted), we fetch it from remote and add an entry
- * for it in {@link savedTrashItemCollectionKeys}.
- *
- * - Once the sync completes, we updated this list to retain only entries that
- * are still referred to by items remaining in the trash.
- */
export const savedTrashItemCollectionKeys = async (): Promise<
TrashItemCollectionKey[]
> =>
TrashItemCollectionKeys.parse(
- // This key name is not accurate, these are not deleted collections but
- // collections referred to by deleted items (so they can include deleted
- // collections, but not exclusively).
- //
- // But since the use of this key name is localized to this file so we
- // let the original name be.
+ // Historical name; this stores every collection key still used by trash.
(await localForage.getItem("deleted-collection")) ?? [],
);
-/**
- * Replace the list of trash item collection keys stored in our local database.
- *
- * This is the setter corresponding to {@link saveTrashItemCollectionKeys}.
- */
export const saveTrashItemCollectionKeys = async (
cks: TrashItemCollectionKey[],
) => {
await localForage.setItem("deleted-collection", cks);
};
-/**
- * Return all files present in our local database.
- *
- * These are "collection files", meaning that there might be multiple entries
- * for the same file, one for each collection that the file belongs to. For more
- * details, See: [Note: Collection File].
- *
- * Use {@link saveCollectionFiles} to update the database.
- */
export const savedCollectionFiles = async (): Promise<EnteFile[]> => {
- // [Note: Avoiding Zod parsing for large DB arrays]
- //
- // Zod can be used to validate that the value we read from the DB is indeed
- // the same as the type we expect, but for potentially very large arrays,
- // this has an overhead that is perhaps not justified when dealing with DB
- // entries we ourselves wrote.
- //
- // For example (as a non-rigorous benchmark) parsing 200k files took one
- // second. Zod is fast, just that these arrays are big and might be accessed
- // frequently, and the schemas are, while not too complicated, non-trivial.
- //
- // As an optimization, we skip the runtime check here and cast. This might
- // not be the most optimal choice in the future, so (a) use it sparingly,
- // and (b) mark all such cases with the title of this note.
- //
- // Note that the cast is happening inside the local forage code since we're
- // passing a type parameter.
+ // Zod parsing 200k self-written records costs about a second.
let files = (await localForage.getItem<EnteFile[]>("files")) ?? [];
- // Previously hidden files were stored separately. If that key is present,
- // also read those files, and migrate them (save the concatenation to disk
- // and delete the corresponding DB key).
- //
- // This migration was added Jun 2025, v1.7.14-beta (tag: Migration).
+ // TODO: Remove this June 2025 hidden-file migration when obsolete.
const previousHiddenFiles =
await localForage.getItem<EnteFile[]>("hidden-files");
if (previousHiddenFiles) {
files = files.concat(previousHiddenFiles);
await saveCollectionFiles(files);
await localForage.removeItem("hidden-files");
- // While we're cleaning up, also remove this unused field related to
- // hidden collections also being separately stored earlier.
await localForage.removeItem("hidden-collection-ids");
}
return transformFilesIfNeeded(files);
};
-/**
- * Replace the list of collection files stored in our local database.
- *
- * This is the setter corresponding to {@link savedCollectionFiles}.
- */
export const saveCollectionFiles = async (files: EnteFile[]) => {
await localForage.setItem("files", transformFilesIfNeeded(files));
};
-/**
- * Return the locally persisted "last sync time" for a collection that we have
- * pulled from remote. This can be used to perform a paginated delta pull from
- * the saved time onwards.
- *
- * > Specifically, this is the {@link updationTime} of the latest file from the
- * > {@link collection}, or the the collection itself if it is fully synced.
- *
- * Use {@link saveCollectionLastSyncTime} to update the value saved in the
- * database, and {@link removeCollectionIDLastSyncTime} to remove the saved
- * value from the database.
- */
export const savedCollectionLastSyncTime = async (collection: Collection) =>
LocalTimestamp.parse(await localForage.getItem(`${collection.id}-time`));
-/**
- * Update the locally persisted timestamp that will be returned by subsequent
- * calls to {@link savedCollectionLastSyncTime}.
- */
export const saveCollectionLastSyncTime = async (
collection: Collection,
time: number,
@@ -205,55 +75,28 @@ export const saveCollectionLastSyncTime = async (
await localForage.setItem(`${collection.id}-time`, time);
};
-/**
- * Remove the locally persisted timestamp, if any, previously saved for a
- * collection with the given ID using {@link saveCollectionLastSyncTime}.
- */
export const removeCollectionIDLastSyncTime = async (collectionID: number) => {
await localForage.removeItem(`${collectionID}-time`);
};
-/**
- * Zod schema for a trash entry saved in our local database.
- */
const LocalTrashItem = z.looseObject({
file: LocalEnteFile,
updatedAt: z.number(),
deleteBy: z.number(),
});
-/**
- * Return all trash entries present in our local database.
- *
- * Use {@link saveTrashItems} to update the database
- */
export const savedTrashItems = async (): Promise<TrashItem[]> =>
LocalTrashItem.array().parse(
(await localForage.getItem("file-trash")) ?? [],
);
-/**
- * Replace the list of trash items stored in our local database.
- *
- * This is the setter corresponding to {@link savedTrashItems}.
- */
export const saveTrashItems = async (trashItems: TrashItem[]) => {
await localForage.setItem("file-trash", trashItems);
};
-/**
- * Return the updatedAt of the latest trash items we have obtained from remote.
- *
- * Use {@link saveTrashLastUpdatedAt} to update the database.
- */
export const savedTrashLastUpdatedAt = async (): Promise<number | undefined> =>
LocalTimestamp.parse(await localForage.getItem("trash-time"));
-/**
- * Update the updatedAt of the latest trash items we have obtained from remote.
- *
- * This is the setter corresponding to {@link savedTrashLastUpdatedAt}.
- */
export const saveTrashLastUpdatedAt = async (updatedAt: number) => {
await localForage.setItem("trash-time", updatedAt);
};
diff --git a/web/packages/new/photos/services/trash.ts b/web/packages/new/photos/services/trash.ts
index d42dde4246..23cfe4cdf8 100644
--- a/web/packages/new/photos/services/trash.ts
+++ b/web/packages/new/photos/services/trash.ts
@@ -18,50 +18,16 @@ import {
saveTrashLastUpdatedAt,
} from "./photos-fdb";
-/**
- * A trash item indicates a file in trash.
- *
- * On being deleted by the user, files move to trash, and gain this associated
- * trash item, which we can fetch with correspoding diff APIs etc. Files will be
- * permanently deleted after 30 days of being moved to trash, but can be
- * restored or permanently deleted before that by explicit user action.
- *
- * See: [Note: File lifecycle]
- */
export interface TrashItem {
file: EnteFile;
- /**
- * Timestamp (epoch microseconds) when the trash entry was last updated.
- */
+ // Both timestamps use epoch microseconds.
updatedAt: number;
- /**
- * Timestamp (epoch microseconds) when the trash item (along with its
- * associated {@link EnteFile}) will be permanently deleted.
- */
deleteBy: number;
}
-/**
- * Zod schema for a trash item that we receive from remote.
- */
const RemoteTrashItem = z.looseObject({
file: RemoteEnteFile,
- /**
- * `true` if the file no longer in trash because it was permanently deleted.
- *
- * This field is relevant when we obtain a trash item as part of the trash
- * diff. It indicates that the file which was previously in trash is no
- * longer in the trash because it was permanently deleted.
- */
isDeleted: z.boolean(),
- /**
- * `true` if the file no longer in trash because it was restored to some
- * collection.
- *
- * This field is relevant when we obtain a trash item as part of the trash
- * diff. It indicates that the file which was previously in trash is no
- * longer in the trash because it was restored to a collection.
- */
isRestored: z.boolean(),
updatedAt: z.number(),
deleteBy: z.number(),
@@ -69,63 +35,18 @@ const RemoteTrashItem = z.looseObject({
export type RemoteTrashItem = z.infer<typeof RemoteTrashItem>;
-/**
- * Update our locally saved data about the files and collections in trash by
- * pulling changes from remote.
- *
- * This function uses a delta diff, pulling only changes since the timestamp
- * saved by the last pull.
- *
- * @param collections All the (non-deleted) collections that we know about
- * locally.
- *
- * @param onSetTrashedItems A callback invoked when the locally persisted trash
- * items are updated. This can be used for the UI to also update its state.
- *
- * This callback can be invoked multiple times during the pull (once for each
- * batch that gets pulled and processed). Each time, it gets passed a list of
- * all the items that are present in trash (in an arbitrary order).
- *
- * @param onPruneDeletedFileIDs A callback invoked when files that were
- * previously in trash have now been permanently deleted. This can be used by
- * other subsystems to prune data referring to files that now have been deleted
- * permanently.
- *
- * This callback can be invoked multiple times during the pull (once for each
- * batch that gets processed).
- */
export const pullTrash = async (
collections: Collection[],
onSetTrashedItems: ((trashItems: TrashItem[]) => void) | undefined,
onPruneDeletedFileIDs: (deletedFileIDs: Set<number>) => Promise<void>,
): Promise<void> => {
- // Data structures:
- //
- // `collectionKeyByID` is a map from collection ID => collection key.
- //
- // It is prefilled with all the non-deleted collections available locally
- // (`collections`), and all keys of collections that trash items refererred
- // to the last time we synced (`trashItemCollectionKeys`).
- //
- // > See: [Note: Trash item collection keys]
- //
- // As we iterate over the trash items, if we find a collection whose key is
- // not present in the map, then we fetch that collection from remote, add
- // its entry to the map, and also updated the persisted value corresponding
- // to `trashItemCollectionKeys`.
- //
- // When we're done, we use `collectionKeyByID` to derive a filtered list of
- // keys that are still referred to by the current set of trash items, and
- // set this filtered list as the persisted value of
- // `trashItemCollectionKeys`.
-
+ // Trash can outlive its collection, so persist every key still in use here.
const collectionKeyByID = new Map(collections.map((c) => [c.id, c.key]));
const trashItemCollectionKeys = await savedTrashItemCollectionKeys();
for (const { id, key } of trashItemCollectionKeys) {
collectionKeyByID.set(id, key);
}
- // Trash items, indexed by the file ID of the file they correspond to.
const trashItemsByID = new Map(
(await savedTrashItems()).map((t) => [t.file.id, t]),
);
@@ -135,8 +56,6 @@ export const pullTrash = async (
const { diff, hasMore } = await getTrashDiff(sinceTime);
if (!diff.length) break;
- // IDs of files that we encounter in this batch that have been
- // permanently deleted.
const deletedFileIDs = new Set<number>();
for (const change of diff) {
sinceTime = Math.max(sinceTime, change.updatedAt);
@@ -148,7 +67,6 @@ export const pullTrash = async (
const collectionID = change.file.collectionID;
let collectionKey = collectionKeyByID.get(collectionID);
if (!collectionKey) {
- // See: [Note: Trash item collection keys]
const collection = await getCollectionByID(collectionID);
collectionKey = collection.key;
collectionKeyByID.set(collectionID, collectionKey);
@@ -183,25 +101,11 @@ export const pullTrash = async (
);
};
-/**
- * See {@link FileDiffResponse} for general semantics of diff responses.
- */
const TrashDiffResponse = z.object({
diff: RemoteTrashItem.array(),
hasMore: z.boolean(),
});
-/**
- * Fetch all trash items that have been created or updated since
- * {@link sinceTime}.
- *
- * Remote only, does not modify local state.
- *
- * @param sinceTime The {@link updatedAt} of the most recently updated trash
- * item we have previously fetched from remote. This serves both as a pagination
- * mechanish, and a way to fetch a delta diff the next time the client needs to
- * pull changes from remote.
- */
const getTrashDiff = async (sinceTime: number) => {
const res = await fetch(await apiURL("/trash/v2/diff", { sinceTime }), {
headers: await authenticatedRequestHeaders(),
@@ -210,17 +114,6 @@ const getTrashDiff = async (sinceTime: number) => {
return TrashDiffResponse.parse(await res.json());
};
-/**
- * Sort trash items such that the items which were recently deleted are first.
- *
- * This is a variant of {@link sortFiles}; it sorts {@link items} in place and
- * also returns a reference to the same mutated arrays.
- *
- * Items are sorted in descending order of their time to deletion (that is, the
- * items which were the most recently deleted will be at the top). For items
- * with the same time to deletion, the ordering is in descending order of the
- * item's file's modification or creation date.
- */
export const sortTrashItems = (trashItems: TrashItem[]) =>
trashItems.sort((a, b) => {
if (a.deleteBy == b.deleteBy) {
@@ -235,38 +128,15 @@ export const sortTrashItems = (trashItems: TrashItem[]) =>
return b.deleteBy - a.deleteBy;
});
-/**
- * Return the IDs of all the files that are part of the trash in our local
- * database.
- */
export const savedTrashItemFileIDs = () =>
savedTrashItems().then((items) => new Set(items.map((f) => f.file.id)));
-/**
- * Delete all the items in trash, permanently deleting the files corresponding
- * to them.
- *
- * This updates both remote and our local database.
- */
export const emptyTrash = async () => {
await postTrashEmpty((await savedTrashLastUpdatedAt()) ?? 0);
await saveTrashItems([]);
};
-/**
- * Delete all the items in trash on remote.
- *
- * Remote only, does not modify local state.
- *
- * @param lastUpdatedAt The {@link updatedAt} value of the most recent item in
- * trash for the user that we know about locally. Remote will only delete trash
- * entries with updatedAt timestamp <= this provided lastUpdatedAt.
- *
- * The user's trash is cleaned up in an async manner. This timestamp is used to
- * ensure that newly trashed files are not deleted due to delay in the async
- * operation, and that out of sync clients (who have a stale lastUpdatedAt)
- * do not cause deletion of newer files that they don't know about locally.
- */
+// The cutoff protects files trashed after this client's last pull.
const postTrashEmpty = async (lastUpdatedAt: number) =>
ensureOk(
await fetch(await apiURL("/trash/empty"), {
diff --git a/web/packages/new/photos/services/user-details.ts b/web/packages/new/photos/services/user-details.ts
index feba035a47..895cf68e4f 100644
--- a/web/packages/new/photos/services/user-details.ts
+++ b/web/packages/new/photos/services/user-details.ts
@@ -12,28 +12,12 @@ import {
} from "ente-utils/transform";
import { z } from "zod";
-/**
- * Validity of the plan.
- */
export type PlanPeriod = "month" | "year";
const Subscription = z.object({
- /**
- * Store-specific ID of the product ("plan") that the user has subscribed
- * to. e.g. if the user has subscribed to a plan using Stripe, then this
- * will be the stripeID of the corresponding {@link Plan}.
- *
- * For free plans, the productID will be the constant "free".
- */
productID: z.string(),
- /**
- * Storage (in bytes) that the user can use.
- */
storage: z.number(),
- /**
- * Epoch microseconds indicating the time until which the user's
- * subscription is valid.
- */
+ // Epoch microseconds.
expiryTime: z.number(),
paymentProvider: z.string(),
price: z.string(),
@@ -48,105 +32,45 @@ const Subscription = z.object({
.transform(nullToUndefined),
});
-/**
- * Details about the user's subscription.
- */
export type Subscription = z.infer<typeof Subscription>;
const FamilyMember = z.object({
- /**
- * ID of the family membership.
- */
+ // Family membership ID, not the Ente user ID.
id: z.string(),
- /**
- * Email address of the family member.
- */
email: z.string(),
status: z.enum(["SELF", "INVITED", "ACCEPTED"]),
- /**
- * ID of the family member's Ente account.
- *
- * This is not available until the member joins the family.
- */
+ // Invited members lack these fields until they accept.
userID: z.number().nullish().transform(nullToUndefined),
- /**
- * `true` if this is the admin.
- *
- * This field will not be sent for invited members until they accept.
- */
isAdmin: z.boolean().nullish().transform(nullToUndefined),
- /**
- * Storage used by the family member.
- *
- * This field will not be present for invited members until they accept.
- */
usage: z.number().nullish().transform(nullToUndefined),
- /**
- * Storage limit allocated to the family member.
- *
- * This field will not be present unless the admin for the family plan has
- * configured a member specific limit, in which case this will be the limit
- * (in bytes) specifying the storage which this member can use.
- */
storageLimit: z.number().nullish().transform(nullToUndefined),
});
export type FamilyMember = z.infer<typeof FamilyMember>;
-/**
- * Zod schema for details about the family plan (if any) that the user is a part
- * of.
- */
const FamilyData = z.object({
members: z.array(FamilyMember),
- /**
- * Family admin subscription storage capacity.
- *
- * This excludes add-on and any other bonus storage.
- */
+ // Admin subscription capacity only; excludes bonuses and add-ons.
storage: z.number(),
});
-/**
- * Details about the family plan (if any) that the user is a part of.
- */
export type FamilyData = z.infer<typeof FamilyData>;
const Bonus = z.object({
- /**
- * The type of the bonus.
- */
type: z.string(),
- /**
- * Amount of storage bonus (in bytes) added to the account.
- */
storage: z.number(),
- /**
- * Validity of the storage bonus. If it is 0, it is valid forever.
- */
+ // Zero means the bonus never expires.
validTill: z.number(),
});
-/**
- * Details about an individual bonus applied for the user.
- */
export type Bonus = z.infer<typeof Bonus>;
const BonusData = z.object({
- /**
- * List of bonuses applied for the user.
- */
storageBonuses: Bonus.array().nullish().transform(nullishToEmpty),
});
-/**
- * Information about bonuses applied for the user.
- */
export type BonusData = z.infer<typeof BonusData>;
-/**
- * Zod schema for {@link UserDetails}
- */
const UserDetails = z.object({
email: z.string(),
usage: z.number(),
@@ -159,42 +83,17 @@ const UserDetails = z.object({
export type UserDetails = z.infer<typeof UserDetails>;
-/**
- * Internal in-memory state shared by the functions in this module.
- *
- * This entire object will be reset on logout.
- */
class UserDetailsState {
- /**
- * Subscriptions to {@link UserDetails} updates attached using
- * {@link userDetailsSubscribe}.
- */
userDetailsListeners: (() => void)[] = [];
-
- /**
- * Snapshot of the {@link UserDetails} returned by the
- * {@link userDetailsSnapshot} function.
- */
userDetailsSnapshot: UserDetails | undefined;
}
-/**
- * State shared by the functions in this module. See {@link UserDetailsState}.
- */
let _state = new UserDetailsState();
export const logoutUserDetails = () => {
_state = new UserDetailsState();
};
-/**
- * Read in the locally persisted user details into memory and return them.
- *
- * If there are no compatible locally persisted values, initiate a network
- * request to fetch the latest values (but don't wait for it to complete).
- *
- * This assumes that the user is already logged in.
- */
export const savedUserDetailsOrTriggerPull = async () => {
const saved = UserDetails.safeParse(await getKV("userDetails"));
if (saved.success) {
@@ -202,23 +101,11 @@ export const savedUserDetailsOrTriggerPull = async () => {
return saved.data;
}
+ // Missing or obsolete local data starts a pull without blocking startup.
void pullUserDetails();
return undefined;
};
-/**
- * A function that can be used to subscribe to updates to {@link UserDetails}.
- *
- * [Note: Snapshots and useSyncExternalStore]
- *
- * This subscribe function, along with {@link userDetailsSnapshot}, is meant to
- * be used as arguments to React's {@link useSyncExternalStore}.
- *
- * @param callback A function that will be invoked whenever the result of
- * {@link userDetailsSnapshot} changes.
- *
- * @returns A function that can be used to clear the subscription.
- */
export const userDetailsSubscribe = (onChange: () => void): (() => void) => {
_state.userDetailsListeners.push(onChange);
return () => {
@@ -228,12 +115,6 @@ export const userDetailsSubscribe = (onChange: () => void): (() => void) => {
};
};
-/**
- * Return the last known, cached {@link UserDetails}.
- *
- * This, along with {@link userDetailsSubscribe}, is meant to be used as
- * arguments to React's {@link useSyncExternalStore}.
- */
export const userDetailsSnapshot = () => _state.userDetailsSnapshot;
const setUserDetailsSnapshot = (snapshot: UserDetails) => {
@@ -241,52 +122,23 @@ const setUserDetailsSnapshot = (snapshot: UserDetails) => {
_state.userDetailsListeners.forEach((l) => l());
};
-/**
- * Fetch the user's details from remote and save them in local storage for
- * subsequent lookup, and also update our in-memory snapshots.
- */
export const pullUserDetails = async () => {
const userDetails = await getUserDetails();
await setKV("userDetails", userDetails);
- // Update the email for the local storage user if needed (the user might've
- // changed their email on a different client).
+ // Email may have changed on another client.
const { email } = userDetails;
if (ensureLocalUser().email != email) {
log.info("Updating user email to match fetched user details");
updateSavedLocalUser({ email });
}
- // The gallery listens for updates to userDetails, so a special case, do a
- // deep equality check so as to not rerender it on redundant updates.
- //
- // [Note: Deep equal check]
- //
- // React uses `Object.is` to detect changes, which changes for arrays,
- // objects and combinations thereof even if the underlying data is the same.
- //
- // In many cases, the code can be restructured to avoid this being a
- // problem, or the rerender might be infrequent enough that it is not a
- // problem.
- //
- // However, when used with useSyncExternalStore, there is an easy way to
- // prevent this, by doing a preflight deep equality comparison.
- //
- // There are arguably faster libraries out there that'll do the deep
- // equality check for us, but since it is an infrequent pattern in our code
- // base currently, we just use the JSON serialization.
- //
- // Mark all cases that do this using this note's title so we can audit them
- // if we move to a deep equality comparison library in the future.
-
+ // useSyncExternalStore treats equivalent object identities as changes.
if (JSON.stringify(userDetails) != JSON.stringify(userDetailsSnapshot())) {
setUserDetailsSnapshot(userDetails);
}
};
-/**
- * Fetch the user details for the currently logged in user from remote.
- */
const getUserDetails = async () => {
const res = await fetch(await apiURL("/users/details/v2"), {
headers: await authenticatedRequestHeaders(),
@@ -295,9 +147,6 @@ const getUserDetails = async () => {
return UserDetails.parse(await res.json());
};
-/**
- * Zod schema for an individual plan received in the list of plans.
- */
const Plan = z.object({
id: z.string(),
androidID: z.string().nullish().transform(nullToUndefined),
@@ -310,24 +159,15 @@ const Plan = z.object({
.transform((p) => (p == "month" || p == "year" ? p : undefined)),
});
-/**
- * An individual plan received in the list of plans from remote.
- */
export type Plan = z.infer<typeof Plan>;
const PlansData = z.object({
- freePlan: z.object({
- /* Number of bytes available in the free plan. */
- storage: z.number(),
- }),
+ freePlan: z.object({ storage: z.number() }),
plans: z.array(Plan),
});
export type PlansData = z.infer<typeof PlansData>;
-/**
- * Fetch the list of plans from remote.
- */
export const getPlansData = async (): Promise<PlansData> => {
const res = await fetch(await apiURL("/billing/user-plans"), {
headers: await authenticatedRequestHeaders(),
@@ -336,21 +176,9 @@ export const getPlansData = async (): Promise<PlansData> => {
return PlansData.parse(await res.json());
};
-/**
- * Derive the total usage for the user both when they are on an individual plan,
- * or on a family plan.
- */
export const planUsage = (userDetails: UserDetails) =>
isPartOfFamily(userDetails) ? familyUsage(userDetails) : userDetails.usage;
-/**
- * Ask remote to acknowledge a subscription that was completed via Stripe,
- * updating our local state to reflect the new subscription on successful
- * verification.
- *
- * @param sessionID Arbitrary and optional string passed on completion of the
- * flow. It is forwarded as the verification data to remote.
- */
export const verifyStripeSubscription = async (
sessionID: unknown,
): Promise<Subscription> => {
@@ -369,11 +197,6 @@ export const verifyStripeSubscription = async (
return userDetailsSnapshot()!.subscription;
};
-/**
- * Ask remote to reactivate the user's current Stripe subscription (that user
- * had previously cancelled), updating our local state to reflect the changes on
- * success.
- */
export const activateStripeSubscription = async () => {
ensureOk(
await fetch(await apiURL("/billing/stripe/activate-subscription"), {
@@ -384,10 +207,6 @@ export const activateStripeSubscription = async () => {
return pullUserDetails();
};
-/**
- * Ask remote to cancel the user's current Stripe subscription, updating our
- * local state to reflect the changes on success.
- */
export const cancelStripeSubscription = async () => {
ensureOk(
await fetch(await apiURL("/billing/stripe/cancel-subscription"), {
@@ -400,14 +219,6 @@ export const cancelStripeSubscription = async () => {
const paymentsAppOrigin = "https://payments.ente.com";
-/**
- * Start the flow to purchase or update a subscription by redirecting the user
- * to the payments app.
- *
- * @param productID The Stripe product ID of the plan to purchase.
- *
- * @param action buy or update.
- */
export const redirectToPaymentsApp = async (
productID: string,
action: "buy" | "update",
@@ -417,19 +228,11 @@ export const redirectToPaymentsApp = async (
window.location.href = `${paymentsAppOrigin}?productID=${productID}&paymentToken=${paymentToken}&action=${action}&redirectURL=${redirectURL}`;
};
-/**
- * Return the URL to which the payments app should redirect back on completion
- * of the flow.
- */
const paymentCompletionRedirectURL = () =>
isDesktop
? `${paymentsAppOrigin}/desktop-redirect`
: `${window.location.origin}/gallery`;
-/**
- * Fetch and return a one-time token that can be used to authenticate user's
- * requests to the payments app.
- */
const getPaymentToken = async () => {
const res = await fetch(await apiURL("/users/payment-token"), {
headers: await authenticatedRequestHeaders(),
@@ -439,10 +242,6 @@ const getPaymentToken = async () => {
.paymentToken;
};
-/**
- * Redirect to the Stripe customer portal / dashboard where the user can view
- * details about their subscription and modify their payment method.
- */
export const redirectToCustomerPortal = async () => {
const redirectURL = paymentCompletionRedirectURL();
const res = await fetch(
@@ -454,95 +253,48 @@ export const redirectToCustomerPortal = async () => {
window.location.href = portal.url;
};
-/**
- * Return true if the given {@link Subscription} has not expired.
- */
export const isSubscriptionActive = (subscription: Subscription) =>
subscription.expiryTime > Date.now() * 1000;
-/**
- * Return true if the given {@link Subscription} is active and for a paid plan.
- */
export const isSubscriptionActivePaid = (subscription: Subscription) =>
isSubscriptionActive(subscription) && subscription.productID != "free";
-/**
- * Return true if the given {@link Subscription} is for a free plan.
- */
export const isSubscriptionFree = (subscription: Subscription) =>
subscription.productID == "free";
-/**
- * Return true if the given {@link Subscription} is active and for the given
- * {@link Plan}.
- */
export const isSubscriptionForPlan = (subscription: Subscription, plan: Plan) =>
plan.stripeID === subscription.productID ||
plan.iosID === subscription.productID ||
plan.androidID === subscription.productID;
-/**
- * Return true if the given {@link Subscription} is using Stripe.
- */
export const isSubscriptionStripe = (subscription: Subscription) =>
subscription.paymentProvider == "stripe";
-/**
- * Return true if the given {@link Subscription} has the cancelled attribute.
- */
export const isSubscriptionCancelled = (subscription: Subscription) =>
subscription.attributes?.isCancelled;
-/**
- * Return true if the user (represented by the given {@link userDetails}) is
- * part of a family plan.
- */
export const isPartOfFamily = (userDetails: UserDetails) =>
(userDetails.familyData?.members.length ?? 0) > 0;
-/**
- * Return true if the user (represented by the given {@link userDetails}) is
- * part of a family plan which has members in the family.
- */
export const isPartOfFamilyWithOtherMembers = (userDetails: UserDetails) =>
(userDetails.familyData?.members.length ?? 0) > 1;
-/**
- * Return true if the user (represented by the given {@link userDetails}) is the
- * admin for the family plan.
- */
export const isFamilyAdmin = (userDetails: UserDetails) =>
userDetails.email == familyAdminEmail(userDetails);
-/**
- * Return the member specific storage limit for the user (represented by the
- * given {@link userDetails}).
- */
export const familyMemberStorageLimit = (userDetails: UserDetails) =>
userDetails.familyData?.members.find((m) => m.email == userDetails.email)
?.storageLimit;
-/**
- * Return the email of the admin for the family plan, if any, that the user
- * (represented by the given {@link userDetails}) is a part of.
- */
export const familyAdminEmail = (userDetails: UserDetails) =>
userDetails.familyData?.members.find((x) => x.isAdmin)?.email;
-/**
- * Return the combined usage of all the family members.
- */
export const familyUsage = (userDetails: UserDetails) =>
(userDetails.familyData?.members ?? []).reduce(
(sum, { usage }) => sum + (usage ?? 0),
0,
);
-/**
- * Update remote to indicate that the user wants to leave the family plan that
- * they are part of, then update our local user details by pulling the latest
- * ones from remote.
- */
export const leaveFamily = async () => {
ensureOk(
await fetch(await apiURL("/family/leave"), {
@@ -553,10 +305,6 @@ export const leaveFamily = async () => {
return pullUserDetails();
};
-/**
- * Return true if the given {@link Subscription} has expired, and is also beyond
- * the grace period.
- */
export const isSubscriptionPastDue = (subscription: Subscription) => {
const thirtyDaysMicroseconds = 30 * 24 * 60 * 60 * 1000 * 1000;
const currentTime = Date.now() * 1000;
@@ -567,20 +315,11 @@ export const isSubscriptionPastDue = (subscription: Subscription) => {
);
};
-/**
- * Return the bonuses whose type starts with "ADD_ON" applicable for the user
- * (represented by the given {@link userDetails}).
- */
export const userDetailsAddOnBonuses = (userDetails: UserDetails) =>
userDetails.bonusData?.storageBonuses.filter((bonus) =>
bonus.type.startsWith("ADD_ON"),
) ?? [];
-/**
- * Return true if the user (represented by the given {@link userDetails}) has a
- * exceeded their storage quota (individual or of the family plan they are a
- * part of).
- */
export const hasExceededStorageQuota = (userDetails: UserDetails) => {
let usage: number;
let storage: number;
diff --git a/web/packages/new/photos/services/user-entity/remote.ts b/web/packages/new/photos/services/user-entity/remote.ts
index e543d97213..69bd1f6b2f 100644
--- a/web/packages/new/photos/services/user-entity/remote.ts
+++ b/web/packages/new/photos/services/user-entity/remote.ts
@@ -9,123 +9,27 @@ import { apiURL } from "ente-base/origins";
import { z } from "zod";
import type { EntityType } from ".";
-/**
- * The maximum number of items to fetch in a single diff
- *
- * [Note: Limit of returned items in /diff requests]
- *
- * The various GET /diff API methods, which tell the client what all has changed
- * since a timestamp (provided by the client) take a limit parameter.
- *
- * These diff API calls return all items whose updated at is greater
- * (non-inclusive) than the timestamp we provide. So there is no mechanism for
- * pagination of items which have the exact same updated at.
- *
- * Conceptually, it may happen that there are more items than the limit we've
- * provided, but there are practical safeguards.
- *
- * For file diff, the limit is advisory, and remote may return less, equal or
- * more items than the provided limit. The scenario where it returns more is
- * when more files than the limit have the same updated at. Theoretically it
- * would make the diff response unbounded, however in practice file
- * modifications themselves are all batched. Even if the user were to select all
- * the files in their library and updates them all in one go in the UI, their
- * client app is required (with server side enforcement) to use batched API
- * calls to make those updates. Thus, each of those batches would get distinct
- * updated at values.
- *
- * For entity diff, there are no bulk operations yet that can result in the
- * assignment of the same microsecond to hundreds of items.
- */
+// Diffs paginate by non-inclusive updatedAt, so equal timestamps cannot span pages.
+// Entity writes are not bulked, keeping same-timestamp groups below this limit.
const defaultDiffLimit = 500;
-/**
- * An entry in the user entity diff.
- *
- * Each change either contains the latest data associated with a particular user
- * entity that has been created or updated, or has a flag set to indicate that
- * the corresponding entity has been deleted.
- */
export interface UserEntityChange {
- /**
- * The UUID or nanoid of the entity.
- */
id: string;
- /**
- * Arbitrary (decrypted) data associated with the entity. The format of this
- * data is specific to each entity type.
- *
- * This will not be present for entities that have been deleted on remote.
- */
+ // Deleted entities are represented by undefined data.
data: Uint8Array<ArrayBuffer> | undefined;
- /**
- * Epoch microseconds denoting when this entity was last changed (created or
- * updated or deleted).
- */
+ // Epoch microseconds.
updatedAt: number;
}
-/**
- * Zod schema for a item in the user entity diff.
- */
const RemoteUserEntityChange = z.object({
id: z.string(),
- /**
- * Base64 string containing the encrypted contents of the entity.
- *
- * Will be `null` when isDeleted is true.
- */
encryptedData: z.string().nullable(),
- /**
- * Base64 string containing the decryption header.
- *
- * Will be `null` when isDeleted is true.
- */
header: z.string().nullable(),
- /**
- * `true` if the corresponding entity was deleted.
- */
isDeleted: z.boolean(),
- /**
- * Epoch microseconds when this entity was last updated.
- *
- * This value is suitable for being passed as the `sinceTime` in the diff
- * requests to implement pagination.
- */
updatedAt: z.number(),
});
-/**
- * Fetch the next set of changes (upserts or deletions) to user entities of the
- * given type since the given time.
- *
- * @param type The type of the entities to fetch.
- *
- * @param sinceTime Epoch microseconds. This is used to ask remote to provide us
- * only entities whose {@link updatedAt} is more than the given value. Set this
- * to zero to start from the beginning.
- *
- * @param entityKey The base64 encoded key to use for decrypting the encrypted
- * contents of the user entity.
- *
- * [Note: Diff response will have at most one entry for an id]
- *
- * Unlike git diffs which track all changes, the diffs we get from remote are
- * guaranteed to contain only one entry (upsert or delete) for a particular Ente
- * object. This holds true irrespective of the diff limit.
- *
- * For example, in a user entity diff, it is guaranteed that there will only be
- * at max one entry for a particular entity id. The entry will have no data to
- * indicate that the corresponding entity was deleted. Otherwise, when the data
- * is present, it is taken as the creation of a new entity or the updation of an
- * existing one.
- *
- * This behaviour comes from how remote stores the underlying, say, entities. A
- * diff returns just entities whose updation times greater than the provided
- * since time (limited to the given diff limit). So there will be at most one
- * row for a particular entity id. And if that entity has been deleted, then the
- * row will be a tombstone, so data be absent.
- */
+// Each diff contains at most one latest row or tombstone per entity ID.
export const userEntityDiff = async (
type: EntityType,
sinceTime: number,
@@ -159,11 +63,6 @@ export const userEntityDiff = async (
);
};
-/**
- * Create a new user entity with the given {@link type} on remote.
- *
- * @returns The ID of the newly created entity.
- */
export const postUserEntity = async (
type: EntityType,
{ encryptedData, decryptionHeader }: EncryptedBlobB64,
@@ -181,10 +80,6 @@ export const postUserEntity = async (
return z.object({ id: z.string() }).parse(await res.json()).id;
};
-/**
- * Update an existing remote user entity with the given {@link id} and
- * {@link type}.
- */
export const putUserEntity = async (
id: string,
type: EntityType,
@@ -203,9 +98,6 @@ export const putUserEntity = async (
}),
);
-/**
- * Delete an existing remote user entity with the given {@link id}.
- */
export const deleteUserEntity = async (id: string) =>
ensureOk(
await fetch(await apiURL("/user-entity/entity", { id }), {
@@ -215,24 +107,13 @@ export const deleteUserEntity = async (id: string) =>
);
export const RemoteUserEntityKey = z.object({
- /** Base64 encoded entity key, encrypted with the user's master key. */
encryptedKey: z.string(),
- /** Base64 encoded nonce used during encryption of this entity key. */
header: z.string(),
});
export type RemoteUserEntityKey = z.infer<typeof RemoteUserEntityKey>;
-/**
- * Fetch the encryption key for the given user entity {@link type} from remote.
- *
- * [Note: User entity keys]
- *
- * There is one encryption key (itself encrypted with the user's master key) for
- * each user entity type. If the key doesn't exist on remote, then the client is
- * expected to create one on the user's behalf. Remote will disallow attempts to
- * multiple keys for the same user entity type.
- */
+// Each entity type has one key; clients create it when this returns 404.
export const getUserEntityKey = async (
type: EntityType,
): Promise<RemoteUserEntityKey | undefined> => {
@@ -240,7 +121,6 @@ export const getUserEntityKey = async (
headers: await authenticatedRequestHeaders(),
});
if (!res.ok) {
- // Remote says HTTP 404 Not Found if there is no key yet for the user.
if (res.status == 404) return undefined;
throw new HTTPError(res);
} else {
@@ -248,11 +128,6 @@ export const getUserEntityKey = async (
}
};
-/**
- * Create a new encryption key for the given user entity {@link type} on remote.
- *
- * See: [Note: User entity keys]
- */
export const postUserEntityKey = async (
type: EntityType,
entityKey: RemoteUserEntityKey,