1 file changed, 90 insertions, 12 deletions
diff --git a/extensions/email-libravatar.lua b/extensions/email-libravatar.lua
index 7336baf..812bef5 100644
--- a/extensions/email-libravatar.lua
+++ b/extensions/email-libravatar.lua
@@ -1,15 +1,67 @@
--- This script may be used with the email-filter or repo.email-filter settings in cgitrc.
--- It adds libravatar icons to author names. It is designed to be used with the lua:
--- prefix in filters.
+-- cgit email-filter that shows a Libravatar icon next to author names. Use it
+-- with the email-filter or repo.email-filter setting and the lua: prefix.
 --
--- Requirements:
--- 	luaossl
--- 	<http://25thandclement.com/~william/projects/luaossl.html>
+--     email-filter=lua:/path/to/email-libravatar.lua
 --
+-- SUPPORTED LUA
+--
+-- Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT. Lua 5.5 is not supported, because luaossl
+-- has no 5.5 build.
+--
+-- DEPENDENCY
+--
+--     luaossl    OpenSSL binding, provides openssl.digest
+--                <https://github.com/wahern/luaossl>
+--
+--     # Debian and Ubuntu
+--     sudo apt install luarocks libssl-dev
+--     sudo luarocks --lua-version 5.1 install luaossl
+--
+--     # Fedora
+--     sudo dnf install luarocks openssl-devel
+--     sudo luarocks --lua-version 5.1 install luaossl
+--
+--     # macOS with Homebrew
+--     brew install luarocks openssl
+--     luarocks install luaossl OPENSSL_DIR="$(brew --prefix openssl)"
+--
+-- PRIVACY
+--
+-- Every page view sends the visitor's IP address and a hash of each
+-- committer's email to a third-party service. Leave this filter off if that is
+-- not acceptable for your instance.
+--
+-- The secure CDN is always used, so the icon loads over https and is never
+-- blocked as mixed content. Addresses are hashed with MD5.
 
 local digest = require("openssl.digest")
 
-function md5_hex(input)
+--
+-- ===== CONFIGURATION =====
+--
+
+-- Pixel size of the avatar.
+local avatar_size = 13
+
+-- Fallback style for an address with no avatar. See the Libravatar docs for
+-- the choices, for example retro, identicon, monsterid or mm.
+local default_image = "retro"
+
+-- Avatar endpoint. The secure CDN is used so the image loads over https.
+local base_url = "https://seccdn.libravatar.org/avatar/"
+
+-- Text for the image alt attribute.
+local alt_text = "Libravatar"
+
+--
+-- =========================
+--
+
+-- State shared across the open, write and close calls of one invocation.
+local buffer = ""
+local avatar = nil
+
+local function hash_hex(input)
 	local b = digest.new("md5"):final(input)
 	local x = ""
 	for i = 1, #b do
@@ -18,19 +70,45 @@ function md5_hex(input)
 	return x
 end
 
+-- Take the address, strip the angle brackets if present, then trim and
+-- lowercase as the avatar services expect. Returns nil for a missing or empty
+-- address.
+local function normalize_email(email)
+	if email == nil then
+		return nil
+	end
+	local inner = email:match("<(.*)>")
+	if inner ~= nil then
+		email = inner
+	end
+	email = (email:gsub("^%s*(.-)%s*$", "%1")):lower()
+	if email == "" then
+		return nil
+	end
+	return email
+end
+
 function filter_open(email, page)
 	buffer = ""
-	md5 = md5_hex(email:sub(2, -2):lower())
+	local addr = normalize_email(email)
+	if addr == nil then
+		avatar = nil
+	else
+		avatar = hash_hex(addr)
+	end
 end
 
 function filter_close()
-	baseurl = os.getenv("HTTPS") and "https://seccdn.libravatar.org/" or "http://cdn.libravatar.org/"
-	html("<img src='" .. baseurl .. "avatar/" .. md5 .. "?s=13&amp;d=retro' width='13' height='13' alt='Libravatar' /> " .. buffer)
+	if avatar == nil then
+		-- No usable address, render the name without an icon.
+		html(buffer)
+	else
+		html("<img src='" .. base_url .. avatar .. "?s=" .. avatar_size .. "&amp;d=" .. default_image ..
+			"' width='" .. avatar_size .. "' height='" .. avatar_size .. "' alt='" .. alt_text .. "' /> " .. buffer)
+	end
 	return 0
 end
 
 function filter_write(str)
 	buffer = buffer .. str
 end
-
-