Byrone.Xenia.Caching 0.1.1

.NET 9.0 This package targets .NET 9.0. The package is compatible with this framework or higher. 
dotnet add package Byrone.Xenia.Caching --version 0.1.1
                    


                    

                
NuGet\Install-Package Byrone.Xenia.Caching -Version 0.1.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Byrone.Xenia.Caching" Version="0.1.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Byrone.Xenia.Caching" Version="0.1.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Byrone.Xenia.Caching" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Byrone.Xenia.Caching --version 0.1.1
                    


                    

                
#r "nuget: Byrone.Xenia.Caching, 0.1.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Byrone.Xenia.Caching@0.1.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Byrone.Xenia.Caching&version=0.1.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Byrone.Xenia.Caching&version=0.1.1
                    


                            Install as a Cake Tool

Xenia.Caching

Utilities for working with cached-content and applying caching headers.

Usage

Caching content with HTTP has always been a tricky process. There's a lot of different headers that are needed to be validated and compared in order to cache content efficiently. The Xenia.Caching package tries to make this as easy as possible.

Using this package (and this documentation) assumes you have a basic understanding of how HTTP caching works. If you don't, or would like to find some more information, you can read more here.

Keep in mind that this package only handles creating headers that instruct the browser how the response is allowed to be cached, when it should be revalidated and if the current content is stale (in need of validation). You are still in charge of assigning what content should be cached how and when.

This package also doesn't provide any functionality to cache data on the server, like in a Redis store.

Here's some basic examples on how to cache responses:

using Byrone.Xenia;
using Byrone.Xenia.Utilities;

private readonly struct Response : IResponse
{
    public void Send(Socket client, in Request request)
    {
		System.Span<byte> buffer = stackalloc byte[128];

		// A 'cacheable' is a declaration of how content is allowed to be cached. This example:
		// - should be stored in public cache (machine-wide, allowed to be used for multiple users)
		// - should only be stored for one hour
		// - has an ETag of 'tag' (your ETag should be quoted!)
		var cacheable = new Cacheable(
			CacheType.Public,
			(long)System.TimeSpan.FromHours(1).TotalSeconds,
			"\"tag\""u8
		);

		// You can also declare your response as uncachable like this:
		var cacheable = Cacheable.NoCache;

		// Transform your cacheable into the correct cache headers
		var cacheHeaders = Cache.GetCacheHeaders(buffer, cacheable);

		// Check if the request has any headers declaring it's cache state and if it should revalidate the cache
		if (Cache.IsStale(in request, cacheable)) 
		{
			// When this function returns `true`, your server should fetch/return the response
			var response = StringBuilder.Format(
				stackalloc byte[256],
				$"""
				HTTP/1.1 200 OK
				{cacheHeaders}
				Content-Type: text/html
				Server: xenia-server

				<html><body><h1>This response should be cached by the browser.</h1></body></html>
				"""
			);

			client.Send(response);
		}
		else
		{
			// When this function returns `false`, the browser's cache is still valid, no need to fetch/send the response again.
			var response = StringBuilder.Format(
				stackalloc byte[256],
				$"""
				HTTP/1.1 304 Not Modified
				{cacheHeaders}
				Content-Type: text/html
				Server: xenia-server


				"""
			);

			client.Send(response);
		}
	}
}

Caching is in this example very useless, as the response body is quite small and doesn't take much resources/time to calculate and send. However, HTTP caching can be a powerful tool for optimizing your server. For example, when you have an endpoint that returns a very heavy calculation, that only changes every x amount of time, you should tell the client's browser to cache the response for a while.

Defining cacheables

A cacheable has multiple properties that help you define how to cache your content.

Property Description Allowed values Example
Type The type of cache to use. See the in-code docs for more info. NoCache, Public, Private CacheType.Public
Age How long (in seconds) the browser can save this response before it needs revalidation. 0 – long.MaxValue 60 * 60 (1 hour)
ETag Identifier for a specific version of the resource. This could be a (file)version, but also a hash of the response body. Any valid UTF-8 string "tag-here", "v0.1.0"
Vary Which headers of the response can vary between cached responses. Any valid UTF-8 string "Accept-Language"u8, "Accept-Language, Accept"u8
LastModified The date and time when the server believes the resource was last modified. A System.DateTime value System.DateTime.UtcNow
Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.1 178 10/29/2024