casper

README

go-casper

Package go-casper is Golang implementation of H2O's CASPer (cache-aware server-push).

Go 1.8 is going to support HTTP/2 server push. Server push allows us to send resources like CSS or JavaScript files before the client asks (so we can expect faster page rendering). As described on this post or this issue, one of the important things to use server push is to know when to push. Since it's waste of the network bandwidth (and cause negative effects on response time), you should avoid to push the asset which has already been cached by the client.

To solve these problem, H2O, a server that provides full advantage of HTTP/2 features, introduces CASPer. CASPer maintains a fingerprint of the browser caches (Golomb-compressed bloom filter) as a cookie, and cancels server-push if the fingerprint indicates the client is known to be in possession of the contents.

go-casper implements H2O's CASPer and provides similar fucntinality in any golang http server. It wraps go's standard server push method (see "HTTP/2 Server Push · Go, the unwritten parts" if you don't how to use it) and maintains a fingerprint of browser caches and decides to push or cancel. The fingerprint is generated by using golomb-coded sets (a compressed encoding of Bloom filter).

The full documentation is available on Godoc.

NOTE1: This project is still a proof of concept and still under heavy implementation. API may be changed in future and documentaion is incomplete. This code should not be run in production. Comments are all welcome!

NOTE2: There is a draft by H2O author which defines a HTTP/2 frame type to allow clients to inform the server of their cache's contents 👏 This pacakage can be replace with it in future.

Example

Below is a simple example of usage.

// Initialize casper with false-positive probability 
// 1/64 and number of assets 10.
pusher := casper.New(1<<6, 10)

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {    
    
    // Execute cache aware server push. 
    // 
    // In this example, it generates a fingerprint "JA" and set it
    // as "x-go-casper" cookie value.
    // 
    // If you access this handler first time, it runs server-push.
    // But from next time, with same client, it cancels pushing since 
    // cookie indicates asset has already been cached by the client.
    if _, err := pusher.Push(w, r, []string{"/static/example.js"}, nil); err != nil {
        log.Printf("[ERROR] Failed to push assets: %s", err)
    }

    // ...
})

You can find the complete example here.

Documentation

Overview

Package casper implements H2O's 1 CASPer (cache-aware server push) in golang.

It wraps go's standard server push method and maintains a fingerprint of browser caches and decides to push or cancel. The fingerprint is generated by using golomb-coded sets (compressed encoding of Bloom filter).

Below is a simple example of usage.

// Initialize casper with false-positive probability
// 1/64 and number of assets 10.
pusher := casper.New(1<<6, 10)

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {

    // Execute cache aware server push.
    //
    // In this example, it generates a fingerprint "JA" and set it
    // as "x-go-casper" cookie value.
    //
    // If you access this handler first time, it runs server-push.
    // But from next time, with same client, it cancels pushing since
    // cookie indicates asset has already been cached by the client.
    if _, err := pusher.Push(w, r, []string{"/static/example.js"}, nil); err != nil {
        log.Printf("[ERROR] Failed to push assets: %s", err)
    }

    // ...
})

Index

• type Casper
  • func New(p, n int) *Casper
  • func (c *Casper) Push(w http.ResponseWriter, r *http.Request, targets []string, opts *Options) (*http.Request, error)
  • func (c *Casper) Pushed() []string
• type Options

Types

type Casper

type Casper struct {
	// contains filtered or unexported fields
}

Casper provides a interface for cache-aware HTTP/2 server push.

func New

func New(p, n int) *Casper

New returns a new casper with false positive probability is 1/p and number of contents.

func (*Casper) Push

func (c *Casper) Push(w http.ResponseWriter, r *http.Request, targets []string, opts *Options) (*http.Request, error)

Push initiates an HTTP/2 server push using the given targets and options. Internally, it just calls go's standard server push method (which was added from go1.8).

It generates a fingerprint of pushed targets compressed by Golomb-coding1 and sets it as a special cookie value to the given ResponseWriter. We can use this cookie to determine the browser caches the specific targets or not. So from next time when the server receives a request, it checks the cookie and determine to push or not the given targets.

func (*Casper) Pushed

func (c *Casper) Pushed() []string

Pushed returns the most recent assets pushed by a call to Push. The underlying buffer may will be overwritten by next call to Push.

type Options

type Options struct {
	*http.PushOptions
}

Options includes casper push options.