<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\mail;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\library\LRUCache;
/**
* Cross-user cache of the DNS-derived records used to check mail
* security, keyed by a record type and a lookup name. Checking an
* incoming message can require several remote lookups -- a signer's
* DKIM public key, a sender domain's DMARC policy, and so on -- each
* published in DNS, the same for every recipient, and rarely changed.
* Caching them avoids repeating those lookups on each message view.
*
* The key has two components, the record type (one of the TYPE_
* constants) and the lookup name, so different kinds of record for
* the same domain do not collide. Values are opaque strings: a DKIM
* key body, a DMARC policy string, and so on; the empty string marks
* a lookup that found nothing, cached briefly so a missing record is
* not re-queried every view.
*
* The cache is a process-wide singleton wrapping an LRUCache, so when
* Yioop runs under its own WebSite server (a long-running process)
* the records are shared across requests and across users for free.
* It is also backed by a file under CACHE_DIR, so the records survive
* a restart and are shared when Yioop runs under a web server that
* handles requests in separate processes. Each entry records an
* expiry; the DNS record's own TTL is honored but clamped to a
* configured range.
*
* @author Chris Pollett
*/
class MailRecordCache
{
/**
* The single shared instance, created on first use.
* @var MailRecordCache|null
*/
private static $instance = null;
/**
* In-memory store of key => [value, expiry] entries.
* @var LRUCache
*/
private $entries;
/**
* Absolute path of the file the cache is persisted to.
* @var string
*/
private $file;
/**
* Whether the persistent file has been read into memory yet.
* @var bool
*/
private $loaded;
/**
* Record type for a signer's DKIM public key, looked up at
* <selector>._domainkey.<domain>.
*/
const TYPE_DKIM = 'dkim';
/**
* Record type for a sender domain's DMARC policy, looked up at
* _dmarc.<domain>.
*/
const TYPE_DMARC = 'dmarc';
/**
* Record type for a domain's SPF policy, the v=spf1 TXT record
* looked up at the domain itself.
*/
const TYPE_SPF = 'spf';
/**
* Number of records kept before the least recently used are
* evicted.
*/
const SIZE = 200;
/**
* File the cache is persisted to, within CACHE_DIR.
*/
const CACHE_FILE = 'mail_records.json';
/**
* Sets up an empty in-memory store and notes the file the cache
* persists to. The file is read lazily on first access.
*/
public function __construct()
{
$this->entries = new LRUCache(self::SIZE);
$this->file = C\CACHE_DIR . "/" . self::CACHE_FILE;
$this->loaded = false;
}
/**
* Returns the shared cache instance, creating it on first call.
*
* @return MailRecordCache the process-wide cache
*/
public static function getInstance()
{
if (self::$instance === null) {
self::$instance = new self();
}
return self::$instance;
}
/**
* Replaces the shared instance with one that persists to a given
* file, or clears it when passed null so the next getInstance
* rebuilds the default. Used by tests to point the cache at a
* throwaway file rather than the real CACHE_DIR; not used in
* normal operation.
*
* @param string|null $file path to persist to, or null to reset
*/
public static function setInstanceFile($file)
{
if ($file === null) {
self::$instance = null;
return;
}
$cache = new self();
$cache->file = $file;
self::$instance = $cache;
}
/**
* Looks up a cached record by its type and name. Returns the
* stored value when the entry is present and unexpired: the
* record body for a found record, or the empty string for a
* cached miss. Returns null when there is no usable entry, which
* tells the caller to perform a fresh DNS lookup.
*
* @param string $type one of the TYPE_ constants
* @param string $name the DNS name the record was looked up at
* @return string|null the cached value, or null on a miss
*/
public function get($type, $name)
{
$this->load();
$entry = $this->entries->get(self::composeKey($type, $name));
if (!is_array($entry)) {
return null;
}
list($value, $expiry) = $entry;
if ($expiry < time()) {
return null;
}
return $value;
}
/**
* Stores a looked-up record under its type and name with an
* expiry computed from the time to live. A found record uses the
* DNS record's TTL clamped to the configured min and max; an
* empty value (nothing found) uses the shorter miss time. The
* whole cache is written back to the persistent file so other
* processes see the entry.
*
* @param string $type one of the TYPE_ constants
* @param string $name the DNS name the record was looked up at
* @param string $value the record body, or '' for a miss
* @param int $time_to_live the DNS record's TTL in seconds; used
* only for a found record, and clamped to the configured
* range
*/
public function put($type, $name, $value, $time_to_live)
{
$this->load();
if ($value === '') {
$lifetime = C\MAIL_RECORD_CACHE_MISS;
} else {
$lifetime = max(C\MAIL_RECORD_CACHE_MIN,
min(C\MAIL_RECORD_CACHE_MAX, (int) $time_to_live));
}
$this->entries->put(self::composeKey($type, $name),
[$value, time() + $lifetime]);
$this->save();
}
/**
* Joins a record type and name into the single string the
* underlying store is keyed by. A null byte separates the two
* components so neither can be confused for the other.
*
* @param string $type one of the TYPE_ constants
* @param string $name the DNS name the record was looked up at
* @return string the composite store key
*/
private static function composeKey($type, $name)
{
return $type . "\x00" . $name;
}
/**
* Reads the persistent file into the in-memory store on first
* access. Expired entries are dropped as they are read. A
* missing or unreadable file leaves the cache empty, which is
* harmless: lookups simply fall through to DNS.
*/
private function load()
{
if ($this->loaded) {
return;
}
$this->loaded = true;
if (!file_exists($this->file)) {
return;
}
$contents = @file_get_contents($this->file);
if ($contents === false || $contents === '') {
return;
}
$decoded = json_decode($contents, true);
if (!is_array($decoded)) {
return;
}
$now = time();
foreach ($decoded as $key => $entry) {
if (!is_array($entry) || count($entry) != 2) {
continue;
}
if ($entry[1] < $now) {
continue;
}
$this->entries->put($key, $entry);
}
}
/**
* Writes the in-memory store back to the persistent file. The
* write goes to a temporary file that is then renamed over the
* target, so a concurrent reader never sees a half-written file.
* Failure to write is ignored: the cache still works in memory
* for the life of the process.
*/
private function save()
{
$directory = dirname($this->file);
if (!is_dir($directory)) {
return;
}
$encoded = json_encode($this->entries->getAll());
if ($encoded === false) {
return;
}
$temporary = $this->file . '.' . getmypid() . '.tmp';
if (@file_put_contents($temporary, $encoded) === false) {
return;
}
@rename($temporary, $this->file);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software