<commit_before>/*
  Package `servefiles` provides a static asset handler for serving files such as images, stylesheets and
  javascript code. This is an enhancement to the standard net/http ServeFiles, which is used internally.
  Care is taken to set headers such that the assets will be efficiently cached by browsers and proxies.

      assets := servefiles.AssetHandler(0, "./assets/", time.Hour)

  Assets is an http.Handler and can be used alongside your other handlers.


  Gzipping

  The Assets handler serves gzipped content when the browser indicates it can accept it. But it does not
  gzip anything on-the-fly. Nor does it create any gzipped files for you.

  During the preparation of your web assets, all text files (CSS, JS etc) should be accompanied by their gzipped
  equivalent. The Assets handler will first look for the gzipped file, which it will serve if present. Otherwise
  it will serve the 'normal' file.

  This has many benefits: fewer bytes are read from the disk, a smaller memory footprint is needed in the server,
  less data copying happens, fewer bytes are sent across the network, etc.

  You should not attempt to gzip already-compressed files, such as PNG, JPEG, SVGZ, etc.

  Very small files gain little from compression because they may be small enough to fit within a single TCP packet,
  so don't bother with them. (They might even grow in size when gzipped.)


  Cache Control

  The 'far-future' technique can and should be used. Set a long expiry time, e.g. time.Hour * 24 * 365 * 10

  Browsers will cache such assets and not make requests for them for the next ten years (or whatever). Not even
  conditional requests are made. There is clearly a big benefit in page load times after the first visit.

  No in-memory caching is performed server-side. This is less needed due to far-future caching being
  supported, but might be added in future.


  Example Usage

  Choose any expiry age you like, although ten years seems to work well.
  To serve files with a ten-year expiry, this creates a suitably-configured handler:

      assets := servefiles.AssetHandler( 1, "./assets/", 10 * 365 * 24 * time.Hour )

  Notice here the first parameter is 1 instead of the default, 0. So the first segment of the URL path gets
  discarded. This means, for example, that the URL

      http://example.com/e3b1cf/css/style1.css

  maps to the asset files

      ./assets/css/style1.css
      ./assets/css/style1.css.gz

  without the e3b1cf segment. The benefit of this is that you can use a unique number or hash in that segment (chosen
  for example each time your server starts). Each time that number changes, browsers will see the asset files as
  being new, and they will later drop old versions from their cache regardless of their ten-year lifespan.

  So you get the ten-year lifespan combined with being able to push out changed assets when you need to.
*/
package servefiles
<commit_msg>yet more docs<commit_after>/*
  Package `servefiles` provides a static asset handler for serving files such as images, stylesheets and
  javascript code. This is an enhancement to the standard net/http ServeFiles, which is used internally.
  Care is taken to set headers such that the assets will be efficiently cached by browsers and proxies.

      assets := servefiles.AssetHandler(0, "./assets/", time.Hour)

  Assets is an http.Handler and can be used alongside your other handlers.


  Gzipping

  The Assets handler serves gzipped content when the browser indicates it can accept it. But it does not
  gzip anything on-the-fly. Nor does it create any gzipped files for you.

  During the preparation of your web assets, all text files (CSS, JS etc) should be accompanied by their gzipped
  equivalent. The Assets handler will first look for the gzipped file, which it will serve if present. Otherwise
  it will serve the 'normal' file.

  This has many benefits: fewer bytes are read from the disk, a smaller memory footprint is needed in the server,
  less data copying happens, fewer bytes are sent across the network, etc.

  You should not attempt to gzip already-compressed files, such as PNG, JPEG, SVGZ, etc.

  Very small files gain little from compression because they may be small enough to fit within a single TCP packet,
  so don't bother with them. (They might even grow in size when gzipped.)


  Cache Control

  The 'far-future' technique can and should be used. Set a long expiry time, e.g. time.Hour * 24 * 365 * 10

  Browsers will cache such assets and not make requests for them for the next ten years (or whatever). Not even
  conditional requests are made. There is clearly a big benefit in page load times after the first visit.

  No in-memory caching is performed server-side. This is less needed due to far-future caching being
  supported, but might be added in future.


  Path Stripping

  The Assets handler can optionally strip some path segments from the URL before selecting the asset to be served.

  This means, for example, that the URL

      http://example.com/e3b1cf/css/style1.css

  can map to the asset files

      ./assets/css/style1.css
      ./assets/css/style1.css.gz

  without the e3b1cf segment. The benefit of this is that you can use a unique number or hash in that segment (chosen
  for example each time your server starts). Each time that number changes, browsers will see the asset files as
  being new, and they will later drop old versions from their cache regardless of their ten-year lifespan.

  So you get the far-future lifespan combined with being able to push out changed assets when you need to.


  Example Usage

  To serve files with a ten-year expiry, this creates a suitably-configured handler:

      assets := servefiles.AssetHandler( 1, "./assets/", 10 * 365 * 24 * time.Hour )

  Notice here the first parameter is 1 instead of the default, 0. So the first segment of the URL path gets
  discarded. A larger number is permitted.

  The second parameter names the local directory that holds the asset files. It can be relative or absolute.

  The third parameter is the maximum age to be specified in the cache-control headers. It can be any duration
  from zero upwards.
*/
package servefiles

{'fraction_non_alphanumeric': 0.046215780998389695, 'fraction_numerical': 0.008051529790660225, 'mean_word_length': 3.5170909090909093, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1926022', 'n_tokens_mistral': 1690, 'n_tokens_neox': 1547, 'n_words': 954}