Kingfisher/Sources/Cache/DiskStorage.swift

//
//  DiskStorage.swift
//  Kingfisher
//
//  Created by Wei Wang on 2018/10/15.
//
//  Copyright (c) 2018年 Wei Wang <onevcat@gmail.com>
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.

import Foundation

/// Represents a storage which stores a certain type of value in disk. The value is serialized to data
/// and stored as file in the file system under a specified location.
///
/// You can config a `DiskStorage` in its initializer by passing a `DiskStorage.Config` value.
/// or modifying the `config` property after it being created. `DiskStorage` will use file's attributes to keep
/// track of a file for its expiration or size limitation.
public class DiskStorage<T: DataTransformable> {

    /// Represents the config used in a `DiskStorage`.
    public struct Config {
        
        /// The allocated size limit on disk of the storage in bytes. 0 means no limit.
        public var sizeLimit: UInt
        
        /// The `StorageExpiration` used in this disk storage. Default is `.days(7)`,
        /// means that the disk cache would expire in one week.
        public var expiration: StorageExpiration = .days(7)
        
        /// The preferred extension of cache item. It will be appended to the file name as its extension.
        /// Default is `nil`, means that the cache file does not contain a file extension.
        public var pathExtension: String? = nil
        
        let name: String
        let fileManager: FileManager
        let directory: URL?
        
        var cachePathBlock: ((_ directory: URL, _ cacheName: String) -> URL)! = {
            (directory, cacheName) in
            return directory.appendingPathComponent(cacheName, isDirectory: true)
        }

        /// Creates a config value based on given parameters.
        ///
        /// - Parameters:
        ///   - name: The name of cache. It is used as a part of storage folder. It is used to identify the disk
        ///           storage. Two storages with the same `name` would share the same folder in disk, and it should
        ///           be prevented.
        ///   - sizeLimit: The size limit in bytes for all existing allocated files in the disk storage.
        ///   - fileManager: The `FileManager` used to manipulate files on disk. Default is `FileManager.default`.
        ///   - directory: The URL where the disk storage should live. The storage will use this as the root folder,
        ///                and append a path which is constructed by input `name`. Default is `nil`, indicates that
        ///                the cache directory under user domain mask will be used.
        public init(
            name: String,
            sizeLimit: UInt,
            fileManager: FileManager = .default,
            directory: URL? = nil)
        {
            self.name = name
            self.fileManager = fileManager
            self.directory = directory
            self.sizeLimit = sizeLimit
        }
    }
    
    /// The config used for this disk storage.
    public var config: Config
    
    // The final storage URL on disk, with `name` and `cachePathBlock` considered.
    let directoryURL: URL
    
    let metaChangingQueue: DispatchQueue
    
    /// Creates a disk storage with the given `DiskStorage.Config`.
    ///
    /// - Parameter config: The config used for this disk storage.
    /// - Throws: An error if the folder for storage cannot be got or created.
    public init(config: Config) throws {

        self.config = config

        let url: URL
        if let directory = config.directory {
            url = directory
        } else {
            url = try config.fileManager.url(
                for: .cachesDirectory,
                in: .userDomainMask,
                appropriateFor: nil,
                create: true)
        }

        let cacheName = "com.onevcat.Kingfisher.ImageCache.\(config.name)"
        directoryURL = config.cachePathBlock(url, cacheName)
        
        metaChangingQueue = DispatchQueue(label: cacheName)
        
        try prepareDirectory()
    }

    // Creates the storage folder.
    func prepareDirectory() throws {
        let fileManager = config.fileManager
        let path = directoryURL.path

        guard !fileManager.fileExists(atPath: path) else { return }

        do {
            try fileManager.createDirectory(
                atPath: path,
                withIntermediateDirectories: true,
                attributes: nil)
        } catch {
            throw KingfisherError.cacheError(reason: .cannotCreateDirectory(path: path, error: error))
        }
    }

    func store(
        value: T,
        forKey key: String,
        expiration: StorageExpiration? = nil) throws
    {
        let data: Data
        do {
            data = try value.toData()
        } catch {
            throw KingfisherError.cacheError(reason: .cannotConvertToData(object: value, error: error))
        }

        let fileURL = cacheFileURL(forKey: key)

        let now = Date()
        let attributes: [FileAttributeKey : Any] = [
            // The last access date.
            .creationDate: now,
            // The estimated expiration date.
            .modificationDate: (expiration ?? config.expiration).estimatedExpirationSinceNow
        ]
        config.fileManager.createFile(atPath: fileURL.path, contents: data, attributes: attributes)
    }

    func value(forKey key: String) throws -> T? {
        return try value(forKey: key, actuallyLoad: true)
    }

    func value(forKey key: String, actuallyLoad: Bool) throws -> T? {
        let fileManager = config.fileManager
        let fileURL = cacheFileURL(forKey: key)
        let filePath = fileURL.path
        guard fileManager.fileExists(atPath: filePath) else {
            return nil
        }

        let meta: FileMeta
        do {
            let resourceKeys: Set<URLResourceKey> = [.contentModificationDateKey, .creationDateKey]
            meta = try FileMeta(fileURL: fileURL, resourceKeys: resourceKeys)
        } catch {
            throw KingfisherError.cacheError(
                reason: .invalidURLResource(error: error, key: key, url: fileURL))
        }
        
        if meta.expired { return nil }
        if !actuallyLoad { return T.empty }
        
        do {
            let data = try Data(contentsOf: fileURL)
            let obj = try T.fromData(data)
            metaChangingQueue.async {
                meta.extendExpiration(with: fileManager)
            }
            return obj
        } catch {
            throw KingfisherError.cacheError(reason: .cannotLoadDataFromDisk(url: fileURL, error: error))
        }
    }

    func isCached(forKey key: String) -> Bool {
        do {
            guard let _ = try value(forKey: key, actuallyLoad: false) else { return false }
            return true
        } catch {
            return false
        }
    }

    func remove(forKey key: String) throws {
        let fileURL = cacheFileURL(forKey: key)
        try removeFile(at: fileURL)
    }

    func removeFile(at url: URL) throws {
        try config.fileManager.removeItem(at: url)
    }

    func removeAll() throws {
        try removeAll(skipCreatingDirectory: false)
    }

    func removeAll(skipCreatingDirectory: Bool) throws {
        try config.fileManager.removeItem(at: directoryURL)
        if !skipCreatingDirectory {
            try prepareDirectory()
        }
    }

    func cacheFileURL(forKey key: String) -> URL {
        let fileName = cacheFileName(forKey: key)
        return directoryURL.appendingPathComponent(fileName)
    }

    func cacheFileName(forKey key: String) -> String {
        let hashedKey = key.kf.md5
        if let ext = config.pathExtension {
            return "\(hashedKey).\(ext)"
        }
        return hashedKey
    }

    func allFileURLs(for propertyKeys: [URLResourceKey]) throws -> [URL] {
        let fileManager = config.fileManager

        guard let directoryEnumerator = fileManager.enumerator(
            at: directoryURL, includingPropertiesForKeys: propertyKeys, options: .skipsHiddenFiles) else
        {
            throw KingfisherError.cacheError(reason: .fileEnumeratorCreationFailed(url: directoryURL))
        }

        guard let urls = directoryEnumerator.allObjects as? [URL] else {
            throw KingfisherError.cacheError(reason: .invalidFileEnumeratorContent(url: directoryURL))
        }
        return urls
    }

    func removeExpiredValues() throws -> [URL] {
        let propertyKeys: [URLResourceKey] = [
            .isDirectoryKey,
            .contentModificationDateKey
        ]

        let urls = try allFileURLs(for: propertyKeys)
        let keys = Set(propertyKeys)
        let expiredFiles = urls.filter { fileURL in
            do {
                let meta = try FileMeta(fileURL: fileURL, resourceKeys: keys)
                if meta.isDirectory {
                    return false
                }
                return meta.expired
            } catch {
                return true
            }
        }
        try expiredFiles.forEach { url in
            try removeFile(at: url)
        }
        return expiredFiles
    }

    func removeSizeExceededValues() throws -> [URL] {

        if config.sizeLimit == 0 { return [] } // Back compatible. 0 means no limit.
        
        var size = try totalSize()
        if size < config.sizeLimit { return [] }

        let propertyKeys: [URLResourceKey] = [
            .isDirectoryKey,
            .creationDateKey,
            .totalFileAllocatedSizeKey
        ]
        let keys = Set(propertyKeys)

        let urls = try allFileURLs(for: propertyKeys)
        var pendings: [FileMeta] = urls.compactMap { fileURL in
            guard let meta = try? FileMeta(fileURL: fileURL, resourceKeys: keys) else {
                return nil
            }
            return meta
        }
        pendings.sort(by: FileMeta.lastAccessDate)
        
        var removed: [URL] = []
        let target = config.sizeLimit / 2
        while size >= target, let meta = pendings.popLast() {
            size -= UInt(meta.totalFileAllocatedSize)
            try removeFile(at: meta.url)
            removed.append(meta.url)
        }
        return removed
    }

    // Get the total allocated size of the folder in bytes.
    func totalSize() throws -> UInt {
        let propertyKeys: [URLResourceKey] = [
            .totalFileAllocatedSizeKey
        ]
        let urls = try allFileURLs(for: propertyKeys)
        let keys = Set(propertyKeys)
        let totalSize: UInt = urls.reduce(0) { size, fileURL in
            do {
                let meta = try FileMeta(fileURL: fileURL, resourceKeys: keys)
                return size + UInt(meta.totalFileAllocatedSize)
            } catch {
                return size
            }
        }
        return totalSize
    }
}

extension DiskStorage {
    struct FileMeta {
    
        let url: URL
        
        let lastAccessDate: Date?
        let estimatedExpirationDate: Date?
        let isDirectory: Bool
        let totalFileAllocatedSize: Int
        
        static func lastAccessDate(lhs: FileMeta, rhs: FileMeta) -> Bool {
            return lhs.lastAccessDate ?? .distantPast > rhs.lastAccessDate ?? .distantPast
        }
        
        init(fileURL: URL, resourceKeys: Set<URLResourceKey>) throws {
            let meta = try fileURL.resourceValues(forKeys: resourceKeys)
            self.init(
                fileURL: fileURL,
                lastAccessDate: meta.creationDate,
                estimatedExpirationDate: meta.contentModificationDate,
                isDirectory: meta.isDirectory ?? false,
                totalFileAllocatedSize: meta.totalFileAllocatedSize ?? 0)
        }
        
        init(
            fileURL: URL,
            lastAccessDate: Date?,
            estimatedExpirationDate: Date?,
            isDirectory: Bool,
            totalFileAllocatedSize: Int)
        {
            self.url = fileURL
            self.lastAccessDate = lastAccessDate
            self.estimatedExpirationDate = estimatedExpirationDate
            self.isDirectory = isDirectory
            self.totalFileAllocatedSize = totalFileAllocatedSize
        }
        
        var expired: Bool {
            return estimatedExpirationDate?.isPast ?? true
        }
        
        func extendExpiration(with fileManager: FileManager) {
            guard let lastAccessDate = lastAccessDate,
                  let lastEstimatedExpiration = estimatedExpirationDate else
            {
                return
            }
            
            let originalExpiration: StorageExpiration =
                .seconds(lastEstimatedExpiration.timeIntervalSince(lastAccessDate))
            let attributes: [FileAttributeKey : Any] = [
                .creationDate: Date(),
                .modificationDate: originalExpiration.estimatedExpirationSinceNow
            ]
            do {
                try fileManager.setAttributes(attributes, ofItemAtPath: url.path)
            } catch {
                assertionFailure("[Kingfisher] Updating cache attributes fails at path: \(url), " +
                    "target attributes: \(attributes)")
            }
        }
    }
}