foreseen

A text-based gemini browser with prefetching
git clone git://git.laack.co/foreseen.git
Log | Files | Refs | README | LICENSE

README (3570B)


      1 foreseen
      2 ========
      3 The Gemini browser that looks into the future.
      4 
      5 Requirements
      6 ============
      7 C++ compiler, make, openssl, ncurses
      8 
      9 Installation
     10 ============
     11 Edit config.mk to match your local setup if necessary for building (foreseen
     12 will be installed into /usr/local/bin by default).
     13 
     14 Then run the following command to build and install foreseen:
     15     make install
     16 
     17 (the above command may require root depending on the installation location)
     18 
     19 Usage
     20 =====
     21 foreseen [--help] [--version] [--cache-pages VAR] [--prefetch-links VAR] \
     22          [--search-engine VAR] destination
     23 
     24 Positional arguments:
     25   destination           page to open [nargs=0..1]
     26 
     27 Optional arguments:
     28   -h, --help            shows help message and exits
     29 
     30   -v, --version         prints version information and exits
     31 
     32   -c, --cache-pages     max number of pages for each cache (history, prefetch) \
     33                         [nargs=0..1] [default: 500]
     34 
     35   -p, --prefetch-links  max number of links to prefetch per page (0 disables \ 
     36                         prefetching) [nargs=0..1] [default: 10]
     37 
     38   -e, --search-engine   default search engine [nargs=0..1] \
     39                         [default: "gemini://tlgs.one/search"]
     40 
     41 
     42 Caching
     43 =======
     44 All caching is done in memory with a configurable fifo data structure to limit
     45 cached page count. There are two separate instances of the cache object at any
     46 given time. One for prefetching and one for history.
     47 
     48 Pages fetched with an identity are never cached, and prefetching never sends
     49 requests to hosts you'd use an identity for.
     50 
     51     Prefetch caching:
     52 
     53     One of the main reasons this browser feels so much faster than other Gemini
     54     protocol browsers is because of its optional prefetch caching. This is
     55     enabled by default. When you visit a site without an identity, a thread will
     56     be created that fetches the first 10 links on the page, caching them  if
     57     they return a 2X status code. This enables ~ instantaneous visitation of
     58     those links. Prefetch caching is only enabled when you aren't using an
     59     identity for a domain. Per the gemtext specification, "clients must not 
     60     automatically make any network connections as part of displaying links", 
     61     so this mode of operation may be construed as non-compliant with the 
     62     gemtext specification. I don't believe a file format specification should be
     63     prescriptive about such things. Additionally, if this was a feature in an
     64     HTTP-based web browser, I would disable it. I perceive Gemini as being 
     65     more trustworthy right now and thus am not concerned about having this 
     66     defaulted on. 
     67 
     68     History caching:
     69 
     70     When you visit a page, the page will be cached after it's loaded. 
     71     If the page was in the prefetch cache before, it will be upgraded to the
     72     history cache. This is because visited pages are more important than
     73     prefetched ones. When using identities, history caching only applies
     74     for forwards and backwards navigation, but not when visiting a previous
     75     site via a link or url.
     76 
     77 Identities
     78 ==========
     79 These are specified in:
     80     $HOME/.foreseen/{hostname}/client.crt
     81     $HOME/.foreseen/{hostname}/client.key
     82 
     83 Or for a non-standard port (port != 1965):
     84     $HOME/.foreseen/{hostname}:{port}/client.crt
     85     $HOME/.foreseen/{hostname}:{port}/client.key
     86 
     87 Example:
     88     > tree .foreseen
     89     .foreseen
     90     └── bbs.geminispace.org
     91         ├── client.crt
     92         └── client.key
     93 
     94 Example command to generate keys:
     95     openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -keyout client.key \
     96     -out client.crt -subj "/CN=localhost"