Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/markdown-native-preview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@medialit/api": minor
"@medialit/web": minor
---

Markdown files open in a native reader in the file preview dialog. The dashboard media list and details now include `preview` (`"markdown"` or `null`), which names the native viewer for a file, and `GET /api/apps/:appId/media/:mediaId/content` returns a previewable file's text (up to 2 MB) for public and private files alike, so storage needs no CORS. On phones the preview dialog fills the screen, markdown opens straight into full-screen reading, and an expand button switches between reading and file details on any screen size. The dashboard is now an installable web app with a manifest, home-screen icons and an offline page.
85 changes: 85 additions & 0 deletions apps/api/src/dashboard/routes.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,7 @@ describe("dashboard routes: session and ownership", () => {
["GET", `/api/apps/${appId}/media`],
["GET", `/api/apps/${appId}/media/count`],
["GET", `/api/apps/${appId}/media/stranger-png`],
["GET", `/api/apps/${appId}/media/stranger-png/content`],
["POST", `/api/apps/${appId}/media/signature`, {}],
["POST", `/api/apps/${appId}/media/stranger-png/seal`, {}],
["GET", `/api/apps/${appId}/keys`],
Expand Down Expand Up @@ -634,3 +635,87 @@ describe("dashboard routes: API keys", () => {
assert.equal(revoked.status, 204);
});
});

describe("dashboard routes: native previews", () => {
let docsApp: AppRecord;

before(async () => {
// A separate app keeps the counts in the main app's tests unchanged.
docsApp = await createApp({ userId: owner.id, name: "Docs" });
await addMedia(owner, docsApp, {
mediaId: "readme-md",
mimeType: "text/markdown",
size: 20,
});
await addMedia(owner, docsApp, {
mediaId: "huge-md",
mimeType: "text/markdown",
size: 3 * 1024 * 1024,
});
await addMedia(owner, docsApp, {
mediaId: "notes-txt",
mimeType: "text/plain",
size: 5,
});
});

test("names the native viewer for each file in the list", async () => {
const { status, body } = await json(
"GET",
`/api/apps/${docsApp.appId}/media?limit=100`,
);
assert.equal(status, 200);
const previews = Object.fromEntries(
body.map((item: { mediaId: string; preview: string | null }) => [
item.mediaId,
item.preview,
]),
);
assert.deepEqual(previews, {
"readme-md": "markdown",
"huge-md": "markdown",
"notes-txt": null,
});
});

test("serves markdown as plain text", async () => {
const read = mock.method(mediaService, "getTextContent", async () => ({
status: "ok" as const,
text: "# Hello\n",
}));
const response = await call(
"GET",
`/api/apps/${docsApp.appId}/media/readme-md/content`,
);
assert.equal(response.status, 200);
assert.match(
response.headers.get("content-type") ?? "",
/^text\/plain; charset=utf-8/,
);
assert.equal(response.headers.get("x-content-type-options"), "nosniff");
assert.equal(await response.text(), "# Hello\n");
assert.deepEqual(read.mock.calls[0].arguments[0], {
userId: owner.id,
appId: docsApp.id,
mediaId: "readme-md",
});
});

test("refuses files without a text preview, too large or missing", async () => {
const unsupported = await call(
"GET",
`/api/apps/${docsApp.appId}/media/notes-txt/content`,
);
assert.equal(unsupported.status, 415);
const tooLarge = await call(
"GET",
`/api/apps/${docsApp.appId}/media/huge-md/content`,
);
assert.equal(tooLarge.status, 413);
const missing = await call(
"GET",
`/api/apps/${docsApp.appId}/media/no-such-media/content`,
);
assert.equal(missing.status, 404);
});
});
53 changes: 51 additions & 2 deletions apps/api/src/dashboard/routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import { deploymentMode } from "../billing/catalog";
import mediaService from "../media/service";
import { sealErrorStatus } from "../media/handlers";
import { mediaKind, parseMediaKind } from "../media/kind";
import { mediaPreview } from "../media/preview";
import { getMediaCount, getTotalSpace } from "../media/queries";
import { validatePresigningOptions } from "../signature/handlers";
import { generateSignature } from "../signature/service";
Expand Down Expand Up @@ -175,8 +176,19 @@ function parseMediaSort(value: unknown): MediaSort | undefined {
return MEDIA_SORTS.find((sort) => sort === value);
}

function withKind<T extends { mimeType?: string }>(media: T) {
return { ...media, kind: mediaKind(media.mimeType ?? "") };
/* Adds what the dashboard needs to show a file: its kind for filters and
icons, and which native viewer (if any) can open it. */
function withKind<T extends { mimeType?: string; originalFileName?: string }>(
media: T,
) {
return {
...media,
kind: mediaKind(media.mimeType ?? ""),
preview: mediaPreview(
media.mimeType ?? "",
media.originalFileName ?? "",
),
};
}

type AppSummary = {
Expand Down Expand Up @@ -471,6 +483,43 @@ export function createDashboardRouter(auth: MedialitAuth) {
res.json(withKind(media));
});

/* The text of a file that has a text-based native viewer. Served from
here rather than storage so the browser never needs storage CORS. */
router.get("/api/apps/:appId/media/:mediaId/content", async (req, res) => {
const owned = await ownedApp(req, res);
if (!owned) return;
try {
const content = await mediaService.getTextContent({
userId: owned.user.id,
appId: owned.app.id,
mediaId: String(req.params.mediaId),
});
if (!content) {
res.status(404).json({ error: "Not found" });
return;
}
if (content.status === "unsupported") {
res.status(415).json({
error: "This file has no text preview",
});
return;
}
if (content.status === "tooLarge") {
res.status(413).json({
error: "This file is too large to preview",
});
return;
}
res.setHeader("content-type", "text/plain; charset=utf-8");
res.setHeader("x-content-type-options", "nosniff");
res.setHeader("cache-control", "private, no-store");
res.send(content.text);
} catch (err: any) {
logger.error({ err }, "Could not read file content");
res.status(502).json({ error: "Could not read the file" });
}
});

router.delete("/api/apps/:appId/media/:mediaId", async (req, res) => {
const owned = await ownedApp(req, res);
if (!owned) return;
Expand Down
25 changes: 25 additions & 0 deletions apps/api/src/media/preview.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { isTextPreview, mediaPreview } from "./preview";

test("markdown is recognised by MIME type or, when vague, by extension", () => {
assert.equal(mediaPreview("text/markdown", "notes.txt"), "markdown");
assert.equal(
mediaPreview("text/x-markdown; charset=utf-8", "a"),
"markdown",
);
assert.equal(mediaPreview("text/plain", "README.md"), "markdown");
assert.equal(
mediaPreview("application/octet-stream", "Guide.MARKDOWN"),
"markdown",
);
assert.equal(mediaPreview("", "notes.md"), "markdown");
});

test("other files get no native preview", () => {
assert.equal(mediaPreview("text/plain", "notes.txt"), null);
assert.equal(mediaPreview("image/png", "diagram.md"), null);
assert.equal(mediaPreview("application/pdf", "doc.pdf"), null);
assert.equal(isTextPreview(null), false);
assert.equal(isTextPreview("markdown"), true);
});
39 changes: 39 additions & 0 deletions apps/api/src/media/preview.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
import path from "path";

/* Files the dashboard can show in a native viewer instead of the generic
preview. The web app picks a viewer by this name, so adding a viewer means
adding a name here and a matching viewer there. */
export const MEDIA_PREVIEWS = ["markdown"] as const;
export type MediaPreview = (typeof MEDIA_PREVIEWS)[number];

/* Text viewers load the whole file, so they stop at this size. */
export const MAX_TEXT_PREVIEW_BYTES = 2 * 1024 * 1024;

const MARKDOWN_MIME_TYPES = new Set(["text/markdown", "text/x-markdown"]);
const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdown", ".mkd"]);

/* Browsers often upload markdown as text/plain or octet-stream, so the file
name decides when the MIME type is that vague. */
const VAGUE_MIME_TYPES = new Set([
"",
"text/plain",
"application/octet-stream",
]);

export function mediaPreview(
mimeType: string,
fileName: string,
): MediaPreview | null {
const type = mimeType.toLowerCase().split(";")[0].trim();
const extension = path.extname(fileName).toLowerCase();
if (MARKDOWN_MIME_TYPES.has(type)) return "markdown";
if (VAGUE_MIME_TYPES.has(type) && MARKDOWN_EXTENSIONS.has(extension)) {
return "markdown";
}
return null;
}

/* Every current preview reads the file as text. */
export function isTextPreview(preview: MediaPreview | null): boolean {
return preview === "markdown";
}
73 changes: 55 additions & 18 deletions apps/api/src/media/service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import {
deleteObject,
copyObject,
getObjectTagging,
getObjectBytes,
UploadParams,
} from "../services/s3";
import logger from "../services/log";
Expand All @@ -47,6 +48,7 @@ import getTags from "./utils/get-tags";
import { getPublicFileUrl, getThumbnailUrl } from "./utils/get-public-urls";
import { AccessControl, Constants, MediaWithUserId } from "@medialit/models";
import { MediaResponse } from "./schemas";
import { isTextPreview, MAX_TEXT_PREVIEW_BYTES, mediaPreview } from "./preview";

const generateAndUploadThumbnail = async ({
workingDirectory,
Expand Down Expand Up @@ -341,26 +343,60 @@ async function getPrivateFileUrl(media: MediaWithUserId, thumb?: boolean) {
: await generateSignedUrl(key, bucket);
}

/* Removes a media item's main file and thumbnail from storage. */
async function removeStoredFiles(media: MediaWithUserId): Promise<void> {
// Determine which bucket the main file is in
const mainBucket =
media.temp || media.accessControl === Constants.AccessControl.PRIVATE
? cloudBucket
: cloudPublicBucket;

const mainPath =
media.temp || media.accessControl === Constants.AccessControl.PRIVATE
? Constants.PathKey.PRIVATE
: Constants.PathKey.PUBLIC;

/* Where a media item's main file lives: temp and private files in the
private bucket, sealed public files in the public one. */
function mainFileLocation(media: MediaWithUserId) {
const isPrivate =
media.temp || media.accessControl === Constants.AccessControl.PRIVATE;
const fileExtension = path.extname(media.fileName).replace(".", "");
const key = generateKey({
mediaId: media.mediaId,
path: mainPath,
filename: `main.${fileExtension}`,
return {
Bucket: isPrivate ? cloudBucket : cloudPublicBucket,
Key: generateKey({
mediaId: media.mediaId,
path: isPrivate
? Constants.PathKey.PRIVATE
: Constants.PathKey.PUBLIC,
filename: `main.${fileExtension}`,
}),
};
}

/* The file's text for text-based native viewers. Null when the file is not
found. */
async function getTextContent({
userId,
appId,
mediaId,
}: {
userId: string;
appId: string;
mediaId: string;
}): Promise<
| { status: "ok"; text: string }
| { status: "unsupported" }
| { status: "tooLarge" }
| null
> {
const media = await getMedia({ userId, appId, mediaId });
if (!media) return null;
if (!isTextPreview(mediaPreview(media.mimeType, media.originalFileName))) {
return { status: "unsupported" };
}
if (media.size > MAX_TEXT_PREVIEW_BYTES) return { status: "tooLarge" };
const result = await getObjectBytes({
...mainFileLocation(media),
maxBytes: MAX_TEXT_PREVIEW_BYTES,
});
await deleteObject({ Key: key, Bucket: mainBucket });
if (result.tooLarge) return { status: "tooLarge" };
return {
status: "ok",
text: new TextDecoder("utf-8").decode(result.bytes),
};
}

/* Removes a media item's main file and thumbnail from storage. */
async function removeStoredFiles(media: MediaWithUserId): Promise<void> {
await deleteObject(mainFileLocation(media));

if (media.thumbnailGenerated) {
// Thumbnails are in public bucket if sealed, private bucket if temp
Expand Down Expand Up @@ -560,6 +596,7 @@ const mediaService = {
getPage,
getMediaCount: getMediaCountWithFilter,
getMediaDetails,
getTextContent,
deleteMedia,
deleteMediaMany,
removeStoredFiles,
Expand Down
20 changes: 20 additions & 0 deletions apps/api/src/services/s3.ts
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,26 @@ export const deleteObject = async (params: DeleteParams) => {
return response;
};

/* Reads a whole object into memory. Callers check `ContentLength` against
their own limit first, so pass `maxBytes` to refuse anything larger. */
export const getObjectBytes = async (params: {
Key: string;
Bucket?: string;
maxBytes: number;
}): Promise<{ bytes: Uint8Array; tooLarge: false } | { tooLarge: true }> => {
const bucket = params.Bucket || cloudBucket;
const response = await getS3Client(bucket).send(
new GetObjectCommand({ Bucket: bucket, Key: params.Key }),
);
if ((response.ContentLength ?? 0) > params.maxBytes) {
response.Body?.transformToWebStream().cancel();
return { tooLarge: true };
}
const bytes = await response.Body!.transformToByteArray();
if (bytes.byteLength > params.maxBytes) return { tooLarge: true };
return { bytes, tooLarge: false };
};

export const getObjectTagging = async (params: {
Key: string;
Bucket?: string;
Expand Down
Loading
Loading