MailTemplateRenderer.java

/*
 * Copyright (c) 2007-2026 MetaSolutions AB
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.entrystore.rest.springboot.util;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.io.IOUtils;
import org.entrystore.repository.config.Settings;
import org.entrystore.rest.springboot.util.EmailTemplate.Section;
import org.jetbrains.annotations.Nullable;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URLConnection;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.time.Year;
import java.util.Arrays;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.stream.Collectors;

/**
 * Loads, caches and renders the transactional email templates. Owns everything content-related —
 * subjects, template sources and the {@code __YEAR__} / {@code __DOMAIN__} substitutions — leaving
 * {@code EmailSender} to own transport.
 *
 * <p>The cache is per-bean, not static, so two Spring contexts in one JVM (as in the test suite) do
 * not share or overwrite each other's templates.
 *
 * <p>Population is a deliberate get / load / {@code putIfAbsent} rather than {@code computeIfAbsent}:
 * {@link #loadTemplate} can fetch over HTTP, and {@code computeIfAbsent} would hold the map's bin lock
 * for the duration of that I/O. A concurrent double-load is harmless because the result is
 * idempotent. A failed load is deliberately <em>not</em> cached, so an operator who fixes a bad
 * template path does not need a restart.
 */
@Slf4j
@Component
@RequiredArgsConstructor
public class MailTemplateRenderer {

	private static final int TEMPLATE_FETCH_TIMEOUT_MS = 5_000;

	private static final Set<String> SECTION_NAMES = Arrays.stream(Section.values())
			.map(Section::getMarkerName)
			.collect(Collectors.toUnmodifiableSet());

	// The Spring Environment rather than @Value fields: the subject and template-path keys are
	// carried by the EmailTemplate constants, keeping the enum the single source of key names,
	// defaults and bundled resources.
	private final Environment environment;

	private final Map<EmailTemplate, LoadedTemplate> templateCache = new ConcurrentHashMap<>();

	/** A template as it is rendered: its mail, and for the sign-up template the account-exists notice, if any. */
	private record LoadedTemplate(String mail, @Nullable String existingAccountNotice) {}

	/** The configured subject for {@code template}, or its documented default. */
	public String subject(EmailTemplate template) {
		return environment.getProperty(template.getSubjectKey(), template.getDefaultSubject());
	}

	/** The configured subject for the sign-up mail of {@code section}, falling back to the sign-up subject. */
	public String subject(Section section) {
		return environment.getProperty(section.getSubjectKey(), subject(EmailTemplate.SIGNUP));
	}

	/**
	 * Renders {@code template} — the confirmation, for the sign-up template — with the shared {@code __YEAR__} /
	 * {@code __DOMAIN__} substitutions plus the supplied ones, or returns null when the template cannot be loaded,
	 * the same failure signal the callers turn into a {@code false} return.
	 *
	 * <p>Substitution values are inserted literally. Entries with a null value are skipped, leaving the
	 * placeholder in place, matching the per-placeholder null guards of the previous implementation.
	 */
	public @Nullable String render(EmailTemplate template, Map<String, String> substitutions) {
		LoadedTemplate loaded = resolveCached(template);
		return loaded == null ? null : substitute(loaded.mail(), substitutions);
	}

	/**
	 * Renders the sign-up mail of {@code section} as {@link #render(EmailTemplate, Map)} does, or returns null when
	 * the template cannot be loaded, which is logged per call, or has no such section, which is logged when the
	 * template is loaded.
	 */
	public @Nullable String render(Section section, Map<String, String> substitutions) {
		LoadedTemplate loaded = resolveCached(EmailTemplate.SIGNUP);
		if (loaded == null) {
			return null;
		}
		String mail = switch (section) {
			case NEW_ACCOUNT -> loaded.mail();
			case EXISTING_ACCOUNT -> loaded.existingAccountNotice();
		};
		return mail == null ? null : substitute(mail, substitutions);
	}

	/**
	 * Whether the sign-up template is loaded and lacks {@code section}, which tells a missing section from a template
	 * that cannot be loaded once {@link #render(Section, Map)} returned null. Reads the cache only, so it neither
	 * loads nor logs.
	 */
	boolean isLoadedWithout(Section section) {
		LoadedTemplate loaded = templateCache.get(EmailTemplate.SIGNUP);
		return loaded != null && section == Section.EXISTING_ACCOUNT && loaded.existingAccountNotice() == null;
	}

	private String substitute(String body, Map<String, String> substitutions) {
		String rendered = body
				// Year.now(), not Calendar.getInstance(): the latter honours the default locale's calendar
				// system, so __YEAR__ renders as 2569 under a th-TH default rather than the Gregorian year.
				.replace("__YEAR__", Integer.toString(Year.now().getValue()))
				.replace("__DOMAIN__", resolveBaseUrlHost(environment));
		for (Map.Entry<String, String> substitution : substitutions.entrySet()) {
			if (substitution.getValue() != null) {
				// Literal replace, never replaceAll: the regex form interprets $ and \ in the
				// *replacement* string as group references and escapes, so a display name or
				// confirmation link containing either would corrupt the mail or throw.
				rendered = rendered.replace(substitution.getKey(), substitution.getValue());
			}
		}
		return rendered;
	}

	private @Nullable LoadedTemplate resolveCached(EmailTemplate template) {
		LoadedTemplate cached = templateCache.get(template);
		if (cached != null) {
			return cached;
		}
		LoadedTemplate loaded = resolveTemplate(template);
		if (loaded == null) {
			log.error("Unable to load email template for {}", template.getDescription());
			return null;
		}
		templateCache.putIfAbsent(template, loaded);
		return loaded;
	}

	/**
	 * Loads the template from the configured path, or the bundled classpath template when no path is
	 * configured, and splits the sign-up template into its mails. Returns null when the chosen source cannot be
	 * loaded or its sections are malformed — a configured path that fails does not fall back to the classpath
	 * template.
	 */
	private @Nullable LoadedTemplate resolveTemplate(EmailTemplate template) {
		String templatePath = environment.getProperty(template.getTemplatePathKey());
		String body = templatePath != null
				? loadTemplate(templatePath)
				: loadClasspathTemplate(template.getClasspathResource());
		if (body == null) {
			return null;
		}
		if (template != EmailTemplate.SIGNUP) {
			return new LoadedTemplate(body, null);
		}
		try {
			return splitSections(template, body);
		} catch (IllegalArgumentException e) {
			log.error("The {} email template from {} is malformed: {}", template.getDescription(),
					templatePath != null ? templatePath : "the classpath", e.getMessage());
			return null;
		}
	}

	/**
	 * A template without markers is the confirmation as a whole. A missing notice is logged here, so once per
	 * loaded template rather than per sign-up: it is a standing configuration choice, not a failure.
	 */
	private static LoadedTemplate splitSections(EmailTemplate template, String body) {
		Map<String, String> byName = TemplateSections.split(body, SECTION_NAMES);
		if (byName.isEmpty()) {
			log.warn("The {} email template has no sections, so sign-ups of existing accounts get no notice",
					template.getDescription());
			return new LoadedTemplate(body, null);
		}
		String confirmation = byName.get(Section.NEW_ACCOUNT.getMarkerName());
		if (confirmation == null) {
			throw new IllegalArgumentException("A template with sections needs a <!--BEGIN new-account--> section, "
					+ "or the confirmation text outside it also reaches the notice");
		}
		String notice = byName.get(Section.EXISTING_ACCOUNT.getMarkerName());
		if (notice == null) {
			log.warn("The {} email template has no <!--BEGIN existing-account--> section, so sign-ups of existing "
					+ "accounts get no notice", template.getDescription());
			return new LoadedTemplate(confirmation, null);
		}
		if (notice.contains("__CONFIRMATION_LINK__")) {
			throw new IllegalArgumentException("__CONFIRMATION_LINK__ is outside the <!--BEGIN new-account--> section, "
					+ "so the notice would carry a confirmation button");
		}
		return new LoadedTemplate(confirmation, notice);
	}

	/**
	 * Resolves the host of the configured base URL for {@code __DOMAIN__} substitution, returning an
	 * empty string when the base URL is unset, blank, has no host (e.g., a schemeless value such as
	 * {@code store}), or is not a valid URI. Avoids the {@code URI.create(null)} / {@code getHost()}-is-null
	 * NPEs that previously escaped the email helpers; a misconfigured (but non-blank) base URL is logged.
	 */
	static String resolveBaseUrlHost(Environment environment) {
		String baseUrl = environment.getProperty(Settings.BASE_URL);
		if (baseUrl == null || baseUrl.isBlank()) {
			return "";
		}
		try {
			String host = URI.create(baseUrl).getHost();
			if (host == null) {
				log.warn("Configured base URL '{}' has no host; '__DOMAIN__' in emails will be empty", baseUrl);
				return "";
			}
			return host;
		} catch (IllegalArgumentException e) {
			log.warn("Configured base URL '{}' is not a valid URI; '__DOMAIN__' in emails will be empty", baseUrl);
			return "";
		}
	}

	private static @Nullable String loadClasspathTemplate(String resourceName) {
		try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(resourceName)) {
			if (is == null) {
				// Previously silent, which made a bundled template missing from the jar indistinguishable
				// from a rendering problem. This is the default-configuration path, so it breaks mail for
				// every deployment that does not set an explicit template path.
				log.error("Bundled email template {} is missing from the classpath", resourceName);
				return null;
			}
			return IOUtils.toString(is, StandardCharsets.UTF_8);
		} catch (IOException e) {
			// Stack trace kept, matching loadTemplate: the two failure modes are diagnosed the same way.
			log.error("Failed to load classpath template {}", resourceName, e);
			return null;
		}
	}

	private static @Nullable String loadTemplate(String url) {
		log.debug("Loading template from {}", url);
		try (InputStream is = openTemplate(url)) {
			return IOUtils.toString(is, StandardCharsets.UTF_8);
		} catch (IOException | URISyntaxException e) {
			log.error("Failed to load email template from {}", url, e);
			return null;
		}
	}

	private static InputStream openTemplate(String url) throws IOException, URISyntaxException {
		if (!url.startsWith("http://") && !url.startsWith("https://")) {
			return Files.newInputStream(new File(url).toPath());
		}
		// URL.openStream() inherits the JVM default of no timeout at all, so an unreachable template host
		// would pin one thread per send until the pool is exhausted — and a failed load is deliberately
		// not cached, so every send retries it. These bound the connect and each individual read; note
		// that setReadTimeout is a per-read inactivity timeout, not a deadline for the whole fetch, so a
		// server that drips a byte at a time still holds the thread.
		URLConnection connection = new URI(url).toURL().openConnection();
		connection.setConnectTimeout(TEMPLATE_FETCH_TIMEOUT_MS);
		connection.setReadTimeout(TEMPLATE_FETCH_TIMEOUT_MS);
		return connection.getInputStream();
	}
}