Docs for caching page #316
Conversation
| id: ID @primaryKey | ||
| } | ||
| ``` | ||
| Here, `expiration: 3600` means cached entries expire after an hour. Harper will automatically evict old data and refresh it when needed. By exporting this table, you instantly get a REST API for it at `http://localhost:9926/BreedCache/`. |
There was a problem hiding this comment.
Harper just marks data as expired. It will not optimistically refresh data. The next request from a user to an expired record will result in the refetch and cache being restored.
| } | ||
| class BreedAPI extends Resource { | ||
| async get() { | ||
| return (await fetch(`https://dog-api.com/${this.getId()}`)).json(); |
There was a problem hiding this comment.
Lets break this up into a couple lines for clarity
There was a problem hiding this comment.
Does dog-api actually exist? Remember this is meant to be a functional follow-along guide. Can we find a simple 3rd party resource to use here? Or is this copied from somewhere else?
There was a problem hiding this comment.
We have been using the dog example. Not necessarily dog-api.com but it's just a placeholder
| - Check if “husky” is already in the cache. | ||
| - If not (or if it’s expired), fetch it from https://dog-api.com/husky. | ||
| - Store it in BreedCache so the next request is instant. |
There was a problem hiding this comment.
Aye this is the correct behavior i was talking about above.
|
|
||
| When interacting with cached data, you can also use the `Cache-Control` request header to specify certain caching behaviors. When performing a PUT (or POST) method, you can use the `max-age` directive to indicate how long the resource should be cached (until stale): | ||
| - Passive caching: great for data that doesn’t change often (like dog breed characteristics). | ||
| - Active caching: connect to a subscription or webhook so Harper gets notified when the source changes. Your cache updates immediately, and your users always see fresh data. |
There was a problem hiding this comment.
Got that from here - https://docs.harperdb.io/docs/developers/applications/caching
| GET /my-resource/id | ||
| Cache-Control: only-if-cached, no-store | ||
| ``` | ||
| Caching doesn’t stop at Harper. Because every Harper cache table is a REST API, your clients can cache responses downstream too. Harper automatically tags responses with ETag headers so browsers or edge caches can hold onto data longer. That means your app is fast all the way down—from the source, to Harper, to the client. |
There was a problem hiding this comment.
Not longer but for the "appropriate amount of time"
There was a problem hiding this comment.
This is good progress. But what about a non-third-party caching example? Like what if I have expensive work to do on the requested resource and I want to be caching that? This page needs to be functional so the user can follow along and actually try things out. Can you show more requests demonstrating the caching? Inspecting status codes and things like that? This content mentions some cool topics too like Etags; but fails to mention that the requests have to send those same tags back to the client for subsequent requests to actually be cache hits. https://github.com/HarperDB/react-ssr-example/blob/151685affcf84e50263720ad8f1e0321d2c87fed/caching-test.js#L13-L21 without them you'll get a 200 every time.
This page barely scratches the surface for caching without ever showing off a real example. This doesn't have to go over everything or go deep into everything. I'd expect a really solid example or two and then some more high level information on the other capabilities with links out to either more examples or reference docs. If those examples don't exist yet, then put a note like "example coming soon!" so we can come back around to it. If reference docs don't exist definitely let us know so we can write them!
There was a problem hiding this comment.
It looks like an example of caching a pseudo-expensive response was added, but kind of isolated and contrived. I think what we (both) really wanted was something more along lines the of https://github.com/HarperFast/react-ssr-example/blob/main/resources.js#L37-L43 which shows how to do a layered cache that is internally caching transformations.
| --- | ||
|
|
||
| # Caching | ||
| Harper provides integrated caching features for external data sources. This page documents all schema directives, configuration options, and resource APIs relevant to caching. |
There was a problem hiding this comment.
Our caching system is not just for external data sources. In fact we'd rather our users use Harper as the data source. But we support integration with 3rd party data sources because that is an important pattern for customers. Also why is this page documenting Resource api methods? Those have their own reference page. If you're trying to demonstrate how they integrate with a caching example I think thats better set for the guide page or its own example.
There was a problem hiding this comment.
This looks like great progress, I think this a helpful distinction between explaining caching and providing a reference. It looks like there are still some requests for having an internal caching example and maybe a working API endpoint to use for a working example.
|
|
||
| ```bash | ||
| curl -i http://localhost:9926/BreedCache/husky \ | ||
| -H 'If-None-Match: "1727223589-husky"' |
There was a problem hiding this comment.
Probably good to note that the user's ETag will be different than this example
There was a problem hiding this comment.
Why are we adding back the TOC? This was intentionally removed in #313
The current caching page is more guide-like than a reference page, but still not relevant to the application guide and narrative at hand.
This PR breaks this out into a documentations page and a reference page, and make the docs more narrative.