第9章：对象存储与缓存 —— Bucket 与 CacheCluster

// 上传
const data = Buffer.from(pdfBytes);
const attributes = await ticketAttachments.upload("itinerary-ORD123.pdf", data, {
  contentType: "application/pdf",
});

// 下载
const bytes = await ticketAttachments.download("itinerary-ORD123.pdf");

// 列举（异步迭代器）
for await (const entry of ticketAttachments.list({})) {
  console.log(entry.name, entry.size);
}

// 删除
await ticketAttachments.remove("itinerary-ORD123.pdf");

// 属性与存在性
const attrs = await ticketAttachments.attrs("itinerary-ORD123.pdf");
const exists = await ticketAttachments.exists("itinerary-ORD123.pdf");

export const cdnAssets = new Bucket("cdn-assets", {
  public: true,
  versioned: false,
});

const url = cdnAssets.publicUrl("banner.png");   // 直接可访问的 URL

// 直传：给前端一个限时上传地址
const uploadUrl = await ticketAttachments.signedUploadUrl("user-42/receipt.jpg", {
  ttl: 7200,   // 秒
});

// 直下：给前端一个限时下载地址（桶保持私有）
const downloadUrl = await ticketAttachments.signedDownloadUrl("itinerary-ORD123.pdf", {
  ttl: 7200,
});

import { Uploader } from "encore.dev/storage/objects";

// 只授予上传权限
const uploaderRef = ticketAttachments.ref<Uploader>();

import { CacheCluster } from "encore.dev/storage/cache";

const cluster = new CacheCluster("app-cache", {
  evictionPolicy: "allkeys-lru",
});

// 其他服务引用同一集群
const sameCluster = CacheCluster.named("app-cache");

import { CacheCluster, StringKeyspace, IntKeyspace, StructKeyspace, expireIn } from "encore.dev/storage/cache";

const cluster = new CacheCluster("app-cache", { evictionPolicy: "allkeys-lru" });

// 字符串值：session token
const sessions = new StringKeyspace<{ sessionId: string }>(cluster, {
  keyPattern: "session/:sessionId",
  defaultExpiry: expireIn(3600 * 1000),   // 毫秒
});

await sessions.set({ sessionId: "abc123" }, "user-42");
const uid = await sessions.get({ sessionId: "abc123" });   // string | undefined，miss 返回 undefined
await sessions.delete({ sessionId: "abc123" });

// 数值：计数器
const searchCount = new IntKeyspace<{ route: string }>(cluster, {
  keyPattern: "search-count/:route",
});
await searchCount.increment({ route: "PEK-LAX" }, 1);

// 结构体：缓存整个对象
interface FlightCache { flightNo: string; price: number; }
const flightCache = new StructKeyspace<{ flightNo: string; date: string }, FlightCache>(cluster, {
  keyPattern: "flight/:flightNo/:date",
  defaultExpiry: expireIn(5 * 60 * 1000),
});
await flightCache.set({ flightNo: "CA981", date: "2026-09-01" }, { flightNo: "CA981", price: 458800 });

import { expireIn, expireInSeconds, expireInMinutes, expireInHours, expireDailyAt, neverExpire, keepTTL } from "encore.dev/storage/cache";

await sessions.set(key, value, { expiry: expireInMinutes(30) });  // 覆盖默认过期
await sessions.setIfNotExists(key, value);   // 不存在才写（抢锁场景）
await sessions.replace(key, value);          // 存在才写，miss 抛 CacheMiss