github.com/IRelaxxx/servefiles/v3@v3.4.6/doc.go (about)

     1  // MIT License
     2  //
     3  // Copyright (c) 2016 Rick Beton
     4  //
     5  // Permission is hereby granted, free of charge, to any person obtaining a copy
     6  // of this software and associated documentation files (the "Software"), to deal
     7  // in the Software without restriction, including without limitation the rights
     8  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     9  // copies of the Software, and to permit persons to whom the Software is
    10  // furnished to do so, subject to the following conditions:
    11  //
    12  // The above copyright notice and this permission notice shall be included in all
    13  // copies or substantial portions of the Software.
    14  //
    15  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    16  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    17  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    18  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    19  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    20  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    21  // SOFTWARE.
    22  
    23  /*
    24  Package servefiles provides a static asset handler for serving files such as images, stylesheets and
    25  javascript code. This is an enhancement to the standard net/http ServeFiles, which is used internally.
    26  Care is taken to set headers such that the assets will be efficiently cached by browsers and proxies.
    27  
    28      assets := servefiles.NewAssetHandler("./assets/").WithMaxAge(time.Hour)
    29  
    30  Assets is an http.Handler and can be used alongside your other handlers.
    31  
    32  
    33  Gzipped Content
    34  
    35  The Assets handler serves gzipped content when the browser indicates it can accept it. But it does not
    36  gzip anything on-the-fly. Nor does it create any gzipped files for you.
    37  
    38  During the preparation of your web assets, all text files (CSS, JS etc) should be accompanied by their gzipped
    39  equivalent; your build process will need to do this. The Assets handler will first look for the gzipped file,
    40  which it will serve if present. Otherwise it will serve the 'normal' file.
    41  
    42  This has many benefits: fewer bytes are read from the disk, a smaller memory footprint is needed in the server,
    43  less data copying happens, fewer bytes are sent across the network, etc.
    44  
    45  You should not attempt to gzip already-compressed files, such as PNG, JPEG, SVGZ, etc.
    46  
    47  Very small files (e.g. less than 1kb) gain little from compression because they may be small enough to fit
    48  within a single TCP packet, so don't bother with them. (They might even grow in size when gzipped.)
    49  
    50  
    51  Conditional Request Support
    52  
    53  The Assets handler sets 'Etag' headers for the responses of the assets it finds. Modern browsers need this: they
    54  are then able to send conditional requests that very often shrink responses to a simple 304 Not Modified. This
    55  improves the experience for users and leaves your server free to do more of other things.
    56  
    57  The Etag value is calculated from the file size and modification timestamp, a commonly used approach. Strong
    58  or weak tags are used for plain or gzipped files respectively (the reason is that a given file can be
    59  compressed with different levels of compression, a weak Etag indicates there is not a strict match for the
    60  file's content).
    61  
    62  For further information see RFC7232 https://tools.ietf.org/html/rfc7232.
    63  
    64  
    65  Cache Control
    66  
    67  To go even further, the 'far-future' technique can and should often be used. Set a long expiry time, e.g.
    68  ten years via `time.Hour * 24 * 365 * 10`.
    69  Browsers will cache such assets and not make requests for them for the next ten years (or whatever). Not even
    70  conditional requests are made. There is clearly a big benefit in page load times after the first visit.
    71  
    72  No in-memory caching is performed server-side. This is needed less due to far-future caching being
    73  supported, but might be added in future.
    74  
    75  For further information see RFC7234 https://tools.ietf.org/html/rfc7234.
    76  
    77  
    78  Path Stripping
    79  
    80  The Assets handler can optionally strip some path segments from the URL before selecting the asset to be served.
    81  
    82  This means, for example, that the URL
    83  
    84      http://example.com/e3b1cf/css/style1.css
    85  
    86  can map to the asset files
    87  
    88      ./assets/css/style1.css
    89      ./assets/css/style1.css.gz
    90  
    91  without the /e3b1cf/ segment. The benefit of this is that you can use a unique number or hash in that segment (chosen
    92  for example each time your server starts). Each time that number changes, browsers will see the asset files as
    93  being new, and they will later drop old versions from their cache regardless of their ten-year lifespan.
    94  
    95  So you get the far-future lifespan combined with being able to push out changed assets as often as you need to.
    96  
    97  
    98  SPA support
    99  
   100  There is support for serving SPA webpage by using WithSPA() this serves index.html for all resources that do not have a file extension
   101  
   102  
   103  Example Usage
   104  
   105  To serve files with a ten-year expiry, this creates a suitably-configured handler:
   106  
   107      assets := servefiles.NewAssetHandler("./assets/").StripOff(1).WithMaxAge(10 * 365 * 24 * time.Hour)
   108  
   109  The first parameter names the local directory that holds the asset files. It can be absolute or relative to
   110  the directory in which the server process is started.
   111  
   112  Notice here the StripOff parameter is 1, so the first segment of the URL path gets discarded. A larger number
   113  is permitted.
   114  
   115  The WithMaxAge parameter is the maximum age to be specified in the cache-control headers. It can be any duration
   116  from zero upwards.
   117  */
   118  package servefiles