This is a Node implementation of the Grassland protocol, suitable for use as Express middleware.
See here for a discussion of what the Grassland protocol is and why you want to use it.
This is not an officially supported Google product!
It is an open-source product released under the Apache 2.0 licence
The Grassland middleware can be installed like this:
const repo = grassland('/static', config)
app.use(repo);
The first argument gives the path where the content will be served from, so since it is
set to '/static', you should configure the CDN to use
http://example.com/static
as the origin server.
The config is an object that controls the details of the the Grassland. Many of the fields are passed are passed to the underlying Git implementation, isomorphic-git, and you can find the details of their meanings there.
- username
- password
- token
- oauth2format
- url
- corsProxy
- noGitSuffix
- depth
- since
- exclude
- relative
- headers
Of these, only url
is required -- at least by the software: your
repo may require you to add other security information . There are a few Grassland-specific
fields too:
- prefix -- a prefix added to the path coming from the CDN before it
is sought in the repo. For example, if the prefix is
public
then the request forhttps://example.com/static/commit/63a4fe21/images/background.png
will return the data found at/public/images/background.png
. - storageDir -- a local directory to use as the working directory for the local repo.
- fetchTime -- the minimum time (in minutes) between fetches from the
remote repo. If it is zero, the fetch will never be performed and
the assumption is that the repo at
storageDir
is being updated in some other way.
Of this, only storageDir
is required, but for most applications,
fetchTime
should be set too.
The middleware can be used alone, but then you have to figure out how to point all the URLs requesting static data to the CDN and to the right commit. Since this can be tricky, Grassland provides some functions that will do the work.
The assumption is that there is a single HTML file, served typically from the root, which is created by taking a file from the repo and finding a line that looks like this:
<base href="/" >
then modify it to look like this:
<base href="https://example.thiscdn.com/commit/63a4fe21/" >
where 63a4fe21 is the commit currently pointed to by some
specific tag (perhaps "live" or "prod" or something like that). This
can be accomplished by a method called serveFile()
app.get('/', (req, res) =>
repo.serveFile('public/index.html', 'prod', 'http://example.thiscdn.com/'),
.then((fileText) => res.type('html').send(fileText))
.catch(e => {
console.error(e);
res.status(500).send(e)
})
);
- better tests
- a strategy for dealing with compiled static files
- a strategy for dealing with robots
- stronger security -- right now, the code assumes that everything under the "root" given for your repo is supposed to be entirely public, every version of every file. Obviously, this isn't the case universally.
Copyright 2019 Google LLC
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.