Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Add Core Cache API Support

未关闭
#53 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
停滞
技术栈
python
领域
api, backend

调研方向

从 stubs/wit_world/imports/cache.py 开始，将提议的 wrapper 与现有的 KV Store 流式集成进行比较。验证 hostcall 调用、选项和状态标志映射、错误处理、上下文管理器事务以及兼容 IOBase 的 body 流式传输；完成的标准是：以 wrapper 为重点的测试覆盖这些行为，但不测试 Viceroy 的缓存持久化。

由索引模型根据 Issue 内容生成。

描述

Overview

Add support for Fastly's Core Cache API, providing advanced caching capabilities with request collapsing, stale-while-revalidate, and streaming.

WIT Interface

interface cache {
  use types.{error};
  use http-body.{body};
  use http-req.{request};
  use async-io.{pollable as pending-entry};

  resource entry {
    lookup: static func(key: list<u8>, options: lookup-options) -> result<entry, error>;
    transaction-lookup: static func(key: list<u8>, options: lookup-options) -> result<entry, error>;
    transaction-lookup-async: static func(key: list<u8>, options: lookup-options) -> result<pending-entry, error>;
    transaction-insert: func(options: write-options) -> result<body, error>;
    transaction-insert-and-stream-back: func(options: write-options) -> result<tuple<body, entry>, error>;
    transaction-update: func(options: write-options) -> result<_, error>;
    get-state: func() -> result<lookup-state, error>;
    get-user-metadata: func(max-len: u64) -> result<option<list<u8>>, error>;
    get-body: func(options: get-body-options) -> result<body, error>;
    get-length: func() -> result<option<object-length>, error>;
    get-max-age-ns: func() -> result<option<duration-ns>, error>;
    get-stale-while-revalidate-ns: func() -> result<option<duration-ns>, error>;
    get-age-ns: func() -> result<option<duration-ns>, error>;
    get-hits: func() -> result<option<cache-hit-count>, error>;
    transaction-cancel: func() -> result<_, error>;
  }

  resource replace-entry {
    replace: static func(key: list<u8>, options: replace-options) -> result<replace-entry, error>;
    get-age-ns: func() -> result<option<duration-ns>, error>;
    get-body: func(options: get-body-options) -> result<option<body>, error>;
    get-hits: func() -> result<option<cache-hit-count>, error>;
    get-length: func() -> result<option<object-length>, error>;
    get-max-age-ns: func() -> result<option<duration-ns>, error>;
    get-stale-while-revalidate-ns: func() -> result<option<duration-ns>, error>;
    get-state: func() -> result<option<lookup-state>, error>;
    get-user-metadata: func(max-len: u64) -> result<option<list<u8>>, error>;
  }

  type object-length = u64;
  type duration-ns = u64;
  type cache-hit-count = u64;

  resource extra-lookup-options {
    constructor();
  }

  record lookup-options {
    request-headers: option<borrow<request>>,
    always-use-requested-range: bool,
    extra: option<borrow<extra-lookup-options>>,
  }

  resource extra-write-options {
    constructor();
  }

  record write-options {
    max-age-ns: duration-ns,
    request-headers: option<borrow<request>>,
    vary-rule: option<string>,
    initial-age-ns: option<duration-ns>,
    stale-while-revalidate-ns: option<duration-ns>,
    surrogate-keys: option<string>,
    length: option<object-length>,
    user-metadata: option<list<u8>>,
    edge-max-age-ns: option<duration-ns>,
    sensitive-data: bool,
    extra: option<borrow<extra-write-options>>,
  }

  resource extra-get-body-options;

  record get-body-options {
    %from: option<u64>,
    to: option<u64>,
    extra: option<borrow<extra-get-body-options>>,
  }

  flags lookup-state {
    found,
    usable,
    stale,
    must-insert-or-update,
    usable-if-error,
  }

  resource extra-replace-options {
    constructor();
  }

  enum replace-strategy {
    immediate,
    immediate-force-miss,
    wait,
  }

  record replace-options {
    request-headers: option<borrow<request>>,
    replace-strategy: option<replace-strategy>,
    always-use-requested-range: bool,
    extra: option<borrow<extra-replace-options>>,
  }

  insert: func(key: list<u8>, options: write-options) -> result<body, error>;
  await-entry: func(handle: pending-entry) -> result<entry, error>;
  close-pending-entry: func(handle: pending-entry) -> result<_, error>;
  close-entry: func(handle: entry) -> result<_, error>;
  replace-insert: func(handle: replace-entry, options: write-options) -> result<body, error>;
  close-replace-entry: func(handle: replace-entry) -> result<_, error>;
}

WIT bindings: stubs/wit_world/imports/cache.py

API Design

  • Implement CacheEntry resource wrapper for cache operations
  • Support lookup and transaction-based caching patterns
  • Implement LookupOptions and WriteOptions dataclasses
  • Provide access to cache metadata: age, TTL, hits, state flags
  • Transaction methods: transaction_lookup(), insert(), update(), cancel()
  • Entry body should implement io.IOBase for streaming (similar to KV Store)
  • get_body() returns file-like object that can be read in chunks or passed to stdlib functions

Cross-SDK Comparison: All SDKs provide lookup(), insert(), transaction_lookup() with similar semantics. Rust uses strong typing for state/options enums, Go uses simple structs, JS uses async/Promise-based API. Python should support both blocking operations and context managers for transactions.

Viceroy Testing

Viceroy's cache implementation is limited/stubbed. Testing focus should be on:

  • Verifying hostcall invocations work correctly
  • Testing SDK wrapper logic (option parsing, state flag handling, error mapping)
  • Ensuring body streaming integration functions properly

Do NOT:

  • Try to verify actual cache persistence behavior
  • Create elaborate tests around Viceroy's stubbed functionality
  • Test cache hit/miss logic (this is host behavior, not SDK code)

The goal is to verify our Python wrapper code works, not to test Viceroy's cache implementation.

Reference

主要语言
Python
星标
5
派生
1
30 天内没有已合并 PR

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

fastly/compute-sdk-python 的其他 Issue

查看 fastly/compute-sdk-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。