Difference between revisions of "Pcforever"

From ProgClub
Jump to: navigation, search
(→‎Done: Added Expires header...)
(→‎Notes for implementers: Notes for implementers...)
 
(7 intermediate revisions by the same user not shown)
Line 79: Line 79:
 
  https://www.example.com/theme
 
  https://www.example.com/theme
  
The CACHE format is:
+
The CACHE file-system format is:
  
 
  /cache/xx/yyyy/{link,http,mime,data,gzip}
 
  /cache/xx/yyyy/{link,http,mime,data,gzip}
Line 97: Line 97:
 
== Notes for implementers ==
 
== Notes for implementers ==
  
If you are interested in incorporating this software into your project, here's what you need to know:
+
If you are interested in using this software here's what you need to know:
  
Copy-and-paste your way to victory!
+
After checking out the [https://www.progclub.org/svn/pcrepo/pcforever/tags/latest/0.1 code from svn], or extracting a [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1/?view=tar release tarball], copy config-example.php to config.php and configure your instance. You need to incorporate the software in Apache2 with an Alias to the front-controller, e.g.:
 +
 
 +
Alias /theme /var/www/pcforever/0.1/web/controller.php
  
 
== Notes for developers ==
 
== Notes for developers ==
Line 105: Line 107:
 
If you're looking to set up a development environment for this project here's what you need to know:
 
If you're looking to set up a development environment for this project here's what you need to know:
  
Checkout the software to some place that Apache can serve it. In my case I checkout [https://www.progclub.org/svn/pcrepo/pcforever/branches branches] to ~/pcrepo/pcforever. I then create a soft-link from ~/workspace/pcforever-0.1 to ~/pcrepo/pcforever/0.1, like this:
+
Checkout the software to some place that Apache can serve it. In my case I checkout [https://www.progclub.org/svn/pcrepo/pcforever/branches branches] to ~/pcrepo/pcforever. I then create a symlink from ~/workspace/pcforever-0.1 to ~/pcrepo/pcforever/0.1, like this:
  
 
  ln -s /home/jj5/pcrepo/pcforever/0.1 /home/jj5/workspace/pcforever-0.1
 
  ln -s /home/jj5/pcrepo/pcforever/0.1 /home/jj5/workspace/pcforever-0.1
Line 126: Line 128:
  
 
* [[User:John|JE]] 2014-06-07: revised project documentation
 
* [[User:John|JE]] 2014-06-07: revised project documentation
* [[User:John|JE]] 2014-06-07: set HTTP Expires header to one year
+
* [[User:John|JE]] 2014-06-07: [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1/web/controller.php?revision=1970&pathrev=1970#l30 set HTTP Expires header] to one year
 +
* [[User:John|JE]] 2014-06-07: saved HTTP headers
 
* [[User:John|JE]] 2014-06-06: Released [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1 Version 0.1]
 
* [[User:John|JE]] 2014-06-06: Released [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1 Version 0.1]
 
* [[User:John|JE]] 2014-06-06: Serve from cache if possible (using gzip if possible)
 
* [[User:John|JE]] 2014-06-06: Serve from cache if possible (using gzip if possible)

Latest revision as of 13:08, 8 June 2014

Pcforever is the ProgClub caching HTTP gateway software. That's the software that proxies HTTP requests and caches the results forever. For other projects see projects.

Status

Version 0.1 released!

Administration

Contributors

Members who have contributed to this project. Newest on top.

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Copyright

Copyright 2014, Contributors.

License

Licensed under the New BSD license.

Resources

Downloads

You can get the software from svn or download the latest 0.1 build.

Source code

The repository can be browsed online:

https://www.progclub.org/pcrepo/pcforever/branches/0.1

The latest stable released version of the code is available from:

https://www.progclub.org/svn/pcrepo/pcforever/tags/latest/0.1

Or if you want the latest versions for development purposes:

https://www.progclub.org/svn/pcrepo/pcforever/branches

Links

Specifications

Functional specification

The functional specification describes what the project does.

The software intercepts HTTP requests to a base path, e.g. "/theme". Anything under the base path, e.g. "/theme/all.css" gets checked to see if it's in the cache. If it is in the cache then the software returns its contents (and mime-type) and completes. If it is not in the cache the software proxies the request to another server, e.g. "https://www.example.com/theme/all.css". The results of the proxy request are cached so that next time that resource is requested it is served from the software's local cache. The idea is to have a system that caches upstream HTTP data forever.

Why is that useful? I'm glad you asked! :)

I'm studying at the moment and have temporary access to my university web-server. Access will be revoked when the course completes. When I save pages (in Firefox with File -> Save As) served from the uni server there are some resources that aren't included in the saved page. For example the CSS file uses the 'url' directive and uses root-relative paths to things like /theme/example.png. I need some software to intercept requests for such content (which at the moment just 404) and then continue to provide that content even when I no longer have access to the uni server. Makes sense?

Technical specification

The technical specification describes how the project works.

There is a front-controller controller.php which receives HTTP requests. It is configured for a base path in Apache with something like this:

Alias /theme /var/www/pcforever/0.1/web/controller.php

The CACHE constant is defined as something like:

/var/www/pcforever/0.1/dat

The UPSTREAM constant is defined as something like:

https://www.example.com/theme

The CACHE file-system format is:

/cache/xx/yyyy/{link,http,mime,data,gzip}

Where:

  • xx = first two characters of the SHA1 hash of the resource
  • yyyy = all 20 characters of the SHA1 hash of the resource
  • link = a text file with the upstream URL on the first line
  • http = the HTTP headers received with the content
  • mime = a text file with the content-type on the first line
  • data = a binary file with the content for the request
  • gzip = the gzipped content of the data file

Notes

Notes for implementers

If you are interested in using this software here's what you need to know:

After checking out the code from svn, or extracting a release tarball, copy config-example.php to config.php and configure your instance. You need to incorporate the software in Apache2 with an Alias to the front-controller, e.g.:

Alias /theme /var/www/pcforever/0.1/web/controller.php

Notes for developers

If you're looking to set up a development environment for this project here's what you need to know:

Checkout the software to some place that Apache can serve it. In my case I checkout branches to ~/pcrepo/pcforever. I then create a symlink from ~/workspace/pcforever-0.1 to ~/pcrepo/pcforever/0.1, like this:

ln -s /home/jj5/pcrepo/pcforever/0.1 /home/jj5/workspace/pcforever-0.1

I have Apache using /home/jj5/workspace as its root directory, so I can hit the front-controller via Apache at:

http://localhost/pcforever-0.1/web/controller.php/example/content.png

Tasks

TODO

Things to do, in rough order of priority:

N/A: all done!

Done

Stuff that's done. Latest stuff on top.

  • JE 2014-06-07: revised project documentation
  • JE 2014-06-07: set HTTP Expires header to one year
  • JE 2014-06-07: saved HTTP headers
  • JE 2014-06-06: Released Version 0.1
  • JE 2014-06-06: Serve from cache if possible (using gzip if possible)
  • JE 2014-06-06: Store HTTP response (data, mime-type and gzipped data)
  • JE 2014-06-06: Capture HTTP response (data and mime-type)
  • JE 2014-06-06: Proxy HTTP requests
  • JE 2014-06-06: created project page
  • JE 2014-06-06: created the project in svn