Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Add Core Cache API Support

Đang mở
#53 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
python
Lĩnh vực
api, backend

Hướng nghiên cứu

Bắt đầu với stubs/wit_world/imports/cache.py và so sánh wrapper được đề xuất với tích hợp streaming KV Store hiện có. Xác minh việc gọi hostcall, ánh xạ tùy chọn và cờ trạng thái, xử lý lỗi, các giao dịch bằng context manager và streaming body tương thích với IOBase; được xem là hoàn thành khi các bài kiểm thử tập trung vào wrapper bao quát các hành vi này mà không kiểm thử tính bền vững của cache Viceroy.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
Python
Star
5
Fork
1
Không có pull request nào được merge trong 30 ngày

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của fastly/compute-sdk-python

Tất cả issue của fastly/compute-sdk-python

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.