summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlex Xu (Hello71) <alex_y_xu@yahoo.ca>2020-03-08 20:55:03 -0400
committerAlex Xu (Hello71) <alex_y_xu@yahoo.ca>2020-03-08 20:55:03 -0400
commitf49c9e7c333199ca762719793b6cb626fc856edf (patch)
treeb874f1df8e8c904a40b0854cd8052c5a5f6f39a9
parent33c4460bed1488c9c313f9646514914852b45f32 (diff)
downloadcgit-syntax-highlighting-f49c9e7c333199ca762719793b6cb626fc856edf.tar.xz
cgit-syntax-highlighting-f49c9e7c333199ca762719793b6cb626fc856edf.zip
update documentation
-rw-r--r--README32
-rwxr-xr-xsyntax-highlighting-server.py3
2 files changed, 34 insertions, 1 deletions
diff --git a/README b/README
index 6ba0fbd..09b1bbf 100644
--- a/README
+++ b/README
@@ -1,3 +1,33 @@
Dedicated syntax highlighting server for cgit.
-Mitigates the issue of python import time for cgit source-filters.
+Use a simple HTTP server to highlight source for cgit. Improves performance
+compared to invoking python on every request.
+
+Usage:
+
+1. Run `make install`.
+2. Configure your system to run /usr/lib/cgit/syntax-highlighting-server.py at
+ boot. This can be done by `systemctl enable syntax-highlighting` on systemd
+ machines. Note that syntax-highlighting-server is very insecure. Therefore,
+ do not configure it to listen on a public network.
+3. Set your cgit source filter to syntax-highlighting-client.sh.
+
+Tuning:
+
+By default, syntax-highlighting-server does all work in a single thread. If you
+have a high query load and multiple CPUs, consider setting --listen-mode to
+forking or reuseport.
+
+reuseport mode uses one worker per CPU and is the highest performance mode, but
+requires Linux and additional idle memory (roughly 1-3 MB per worker).
+
+forking mode uses less idle memory and is compatible with non-Linux systems,
+but is significantly less efficient, since it forks for every request.
+
+Security:
+
+syntax-highlighting-server is not hardened against malicious clients which send
+malformed data or are simply excessively slow. Once again, do not configure
+syntax-highlighting-server to listen on a public network. It is also
+recommended to set max-blob-size in cgitrc, as the entire file must be buffered
+in memory during syntax highlighting.
diff --git a/syntax-highlighting-server.py b/syntax-highlighting-server.py
index dabd631..05140a7 100755
--- a/syntax-highlighting-server.py
+++ b/syntax-highlighting-server.py
@@ -117,6 +117,9 @@ def main():
.format(args.host, args.port))
try:
+ # preload stuff to avoid first-request latency (every request for
+ # forking) and post-fork memory usage
+
# preload lexers
guess_lexer('')
# preload formatter