doc/todo/design_for_cross-linking_between_content_and_CGI.mdwn

   1 We're accumulating a significant number of bugs related to cross-linking
   2 between the content and the CGI not being as relative as we would like.
   3 This is an attempt to design a solution for them all in a unified way,
   4 rather than solving one bug at the cost of exacerbating another.
   5 --[[smcv]]
   6
   7 # Terminology
   8
   9 * Absolute: starts with a scheme, like
  10   `http://example.com/ikiwiki.cgi`, `https://www.example.org/`
  11
  12 * Protocol-relative: starts with `//` like `//example.com/ikiwiki.cgi`
  13
  14 * Host-relative: starts with `/` like `/ikiwiki.cgi`
  15
  16 * Relative: starts with neither `/` nor a scheme, like `../ikiwiki.cgi`
  17
  18 # What we need
  19
  20 * Static content must be able to link to other static content
  21
  22 * Static content must be able to link to the CGI
  23
  24 * CGI-generated content must be able to link to arbitrary
  25   static content (it is sufficient for it to be able to link
  26   to the "root" of the `destdir`)
  27
  28 * CGI-generated content must be able to link to the CGI
  29
  30 # Constraints
  31
  32 * URIs in RSS feeds must be absolute, because feed readers do not have
  33   any consistent semantics for the base of relative links
  34
  35 * If we have a `<base href>` then HTML 4.01 says it must be
  36   absolute, although HTML 5 does relax this by defining semantics
  37   for a relative `<base href>` - it is interpreted relative to the
  38   "fallback base URL" which is the URL of the page being viewed
  39   ([[bugs/trouble_with_base_in_search]],
  40   [[bugs/preview_base_url_should_be_absolute]])
  41
  42 * It is currently possible for the static content and the CGI
  43   to be on different domains, e.g. `www.example.com`
  44   vs. `cgi.example.com`; this should be preserved
  45
  46 * It is currently possible to serve static content "mostly over
  47   HTTP" (i.e. advertise a http URI to readers, and use a http
  48   URI in RSS feeds etc.) but use HTTPS for the CGI
  49
  50 * If the static content is served over HTTPS, it must refer
  51   to other static content and the CGI via HTTPS (to avoid
  52   mixed content, which is a vulnerability); this may be
  53   either absolute, protocol-relative, host-relative or relative
  54
  55 * If the CGI is served over HTTPS, it must refer to static
  56   content and the CGI via HTTPS; again, this may be either
  57   either absolute, protocol-relative, host-relative or relative
  58   ([[todo/Protocol_relative_urls_for_stylesheet_linking]])
  59
  60 * Because reverse proxies and `w3mmode` exist, it must be
  61   possible to configure ikiwiki to not believe the `HTTPS`, etc.,
  62   CGI variables, and force a particular scheme or host
  63   ([[bugs/W3MMode_still_uses_http:__47____47__localhost__63__]],
  64   [[forum/Using_reverse_proxy__59___base_URL_is_http_instead_of_https]],
  65   [[forum/Dot_CGI_pointing_to_localhost._What_happened__63__]])
  66
  67 * For relative links in page-previews to work correctly without
  68   having to have global state or thread state through every use of
  69   `htmllink` etc., `cgitemplate` needs to make links in the page body
  70   work as if we were on the page being previewed.
  71
  72 # "Would be nice"
  73
  74 * In general, the more relative the better
  75
  76 * [[schmonz]] wants to direct all CGI pageviews to https
  77   even if the visitor comes from http (but this can be done
  78   at the webserver level by making http://example.com/ikiwiki.cgi
  79   a redirect to https://example.com/ikiwiki.cgi, so is not
  80   necessarily mandatory)
  81
  82 * [[smcv]] has some sites that have non-CA-cartel-approved
  83   certificates, with a limited number of editors who can be taught
  84   to add SSL policy exceptions and log in via https;
  85   anonymous/read-only actions like `do=goto` should
  86   not go via HTTPS, since random readers would get scary SSL
  87   warnings
  88   ([[todo/want_to_avoid_ikiwiki_using_http_or_https_in_urls_to_allow_serving_both]],
  89   [[forum/CGI_script_and_HTTPS]])
  90
  91 * It would be nice if the CGI did not need to use a `<base>` so that
  92   we could use host-relative URI references (`/sandbox/`) or scheme-relative
  93   URI references (`//static.example.com/sandbox/`)
  94   (see [[bugs/trouble_with_base_in_search]])
  95
  96 As a consequence of the "no mixed content" constraint, I think we can
  97 make some assumptions:
  98
  99 * if the `cgiurl` is http but the CGI discovers at runtime that it has
 100   been reached via https, we can assume that the https equivalent,
 101   or a host- or protocol-relative URI reference to itself, would work;
 102
 103 * if the `url` is http but the CGI discovers at runtime that it has been
 104   reached via https, we can assume that the https equivalent of the `url`
 105   would work
 106
 107 In other words, best-practice would be to list your `url` and `cgiurl`
 108 in the setup file as http if you intend that they will most commonly
 109 be accessed via http (e.g. the "my cert is not CA-cartel approved"
 110 use-case), or as https if you intend to force accesses into
 111 being via https (the "my wiki is secret" use-case).
 112
 113 # Regression test
 114
 115 I've added a regression test in `t/relativity.t`. We might want to
 116 consider dropping some of it or skipping it unless a special environment
 117 variable is set once this is all working, since it's a bit slow.
 118 --[[smcv]]
 119
 120 # Remaining bugs
 121
 122 ## Arguable
 123
 124 * Configure the url and cgiurl to both be https, then access the
 125   CGI via a non-https address. The stylesheet is loaded from the http
 126   version of the static site, but maybe it should be forced to https?
 127
 128 * Configure url = "http://static.example.com/",
 129   cgiurl = "http://cgi.example.com/ikiwiki.cgi" and access the
 130   CGI via staging.example.net. Self-referential links to the
 131   CGI point to cgi.example.com, but maybe they should point to
 132   staging.example.net?
 133
 134 * *(possibly incomplete, look for TODO and ??? in relativity.t)*