Difference between revisions of "Pcforever"
(Initial project doco...) |
(→Notes for implementers: Notes for implementers...) |
||
(21 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
= Status = | = Status = | ||
− | + | [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1 Version 0.1] released! | |
= Administration = | = Administration = | ||
Line 27: | Line 27: | ||
== Downloads == | == Downloads == | ||
− | + | You can get the software from [[#Source_code|svn]] or [https://www.progclub.org/pcrepo/pcforever/tags/latest/0.1/?view=tar download the latest 0.1 build]. | |
== Source code == | == Source code == | ||
Line 33: | Line 33: | ||
The repository can be browsed online: | The repository can be browsed online: | ||
− | https://www.progclub.org/pcrepo/pcforever/branches | + | https://www.progclub.org/pcrepo/pcforever/branches/0.1 |
The latest stable released version of the code is available from: | The latest stable released version of the code is available from: | ||
− | https://www.progclub.org/svn/pcrepo/pcforever/tags/latest | + | https://www.progclub.org/svn/pcrepo/pcforever/tags/latest/0.1 |
− | Or if you want the latest | + | Or if you want the latest versions for development purposes: |
https://www.progclub.org/svn/pcrepo/pcforever/branches | https://www.progclub.org/svn/pcrepo/pcforever/branches | ||
Line 45: | Line 45: | ||
== Links == | == Links == | ||
− | + | * [http://php.net/manual/en/function.http-response-code.php http_response_code] and [https://en.wikipedia.org/wiki/List_of_HTTP_status_codes List of HTTP status codes]. | |
+ | * [http://php.net/manual/en/book.curl.php Client URL Library]. | ||
+ | * [https://en.wikipedia.org/wiki/List_of_HTTP_headers List of HTTP headers]. | ||
+ | * [http://php.net/manual/en/function.getenv.php getenv] and [http://www.php.net/manual/en/language.variables.superglobals.php Superglobals]. | ||
+ | * [http://php.net/manual/en/function.gzencode.php gzencode]. | ||
= Specifications = | = Specifications = | ||
Line 63: | Line 67: | ||
The technical specification describes how the project works. | 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: | + | There is a front-controller [https://www.progclub.org/pcrepo/pcforever/branches/0.1/web/controller.php?view=markup 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 | Alias /theme /var/www/pcforever/0.1/web/controller.php | ||
Line 75: | 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/{mime,data} | + | /cache/xx/yyyy/{link,http,mime,data,gzip} |
Where: | Where: | ||
Line 83: | Line 87: | ||
* xx = first two characters of the SHA1 hash of the resource | * xx = first two characters of the SHA1 hash of the resource | ||
* yyyy = all 20 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 | * mime = a text file with the content-type on the first line | ||
* data = a binary file with the content for the request | * data = a binary file with the content for the request | ||
Line 91: | Line 97: | ||
== Notes for implementers == | == Notes for implementers == | ||
− | If you are interested in | + | If you are interested in using this software here's what you need to know: |
− | + | 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 99: | 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 ~/workspace/pcforever. | + | 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: |
− | http://localhost/pcforever | + | 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 = | = Tasks = | ||
Line 109: | Line 121: | ||
Things to do, in rough order of priority: | Things to do, in rough order of priority: | ||
− | + | N/A: all done! | |
− | |||
− | |||
− | |||
− | |||
− | |||
== Done == | == Done == | ||
Line 120: | Line 127: | ||
Stuff that's done. Latest stuff on top. | Stuff that's done. Latest stuff on top. | ||
+ | * [[User:John|JE]] 2014-06-07: revised project documentation | ||
+ | * [[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: Serve from cache if possible (using gzip if possible) | ||
+ | * [[User:John|JE]] 2014-06-06: Store HTTP response (data, mime-type and gzipped data) | ||
+ | * [[User:John|JE]] 2014-06-06: Capture HTTP response (data and mime-type) | ||
+ | * [[User:John|JE]] 2014-06-06: Proxy HTTP requests | ||
* [[User:John|JE]] 2014-06-06: created project page | * [[User:John|JE]] 2014-06-06: created project page | ||
* [[User:John|JE]] 2014-06-06: created the project in svn | * [[User:John|JE]] 2014-06-06: created the project in svn |
Latest revision as of 12: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
- http_response_code and List of HTTP status codes.
- Client URL Library.
- List of HTTP headers.
- getenv and Superglobals.
- gzencode.
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