88 lines
3.2 KiB
Swift
88 lines
3.2 KiB
Swift
/// An asset shipped with a website: a file stored under the static files root and served by Hummingbird's `FileMiddleware` middleware.
|
|
///
|
|
/// A conforming asset supplies its file name and the extensions it is available with, each resolving to its own file; the protocol derives the paths from them:
|
|
/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches. Each file lands in its extension's own
|
|
/// folder unless the asset names a ``folder`` of its own.
|
|
public protocol Asset: Sendable {
|
|
|
|
// MARK: Properties
|
|
|
|
/// The folder within the static files root that holds the asset's files, or `nil` (the default) to use each extension's own folder.
|
|
var folder: String? { get }
|
|
|
|
/// The file extensions the asset is available with.
|
|
var fileExtensions: [AssetExtension] { get }
|
|
|
|
/// The asset's file name, without extension.
|
|
var fileName: String { get }
|
|
|
|
}
|
|
|
|
// MARK: - Implementations
|
|
|
|
public extension Asset {
|
|
|
|
// MARK: Computed
|
|
|
|
/// The asset's files live in each extension's own folder by default.
|
|
var folder: String? { nil }
|
|
|
|
// MARK: Methods
|
|
|
|
/// Resolves the asset's path against the given base directory.
|
|
///
|
|
/// - Parameters:
|
|
/// - basePath: the directory the static files are served from.
|
|
/// - fileExtension: the extension of the file to resolve.
|
|
/// - Returns: the path to the file, relative to the `basePath` path.
|
|
func path(
|
|
relativeTo basePath: String,
|
|
for fileExtension: AssetExtension
|
|
) -> String {
|
|
let relativePath = relativePath(for: fileExtension)
|
|
|
|
guard !basePath.isEmpty else {
|
|
return relativePath
|
|
}
|
|
|
|
return "\(basePath)/\(relativePath)"
|
|
}
|
|
|
|
/// Resolves the asset's path relative to the static files root (e.g. `"css/shared.css"`).
|
|
///
|
|
/// This also matches the URL path the file is served at by `FileMiddleware`.
|
|
///
|
|
/// - Parameter fileExtension: the extension of the file to resolve.
|
|
/// - Returns: the path to the file, relative to the static files root.
|
|
func relativePath(
|
|
for fileExtension: AssetExtension
|
|
) -> String {
|
|
let file = "\(fileName).\(fileExtension.rawValue)"
|
|
|
|
return (folder ?? fileExtension.folder)
|
|
.map { "\($0)/\(file)" } ?? file
|
|
}
|
|
|
|
/// Resolves the absolute URL path the asset is served at (e.g. `"/css/shared.css"`).
|
|
///
|
|
/// A version token appends as a `v` query parameter (e.g. `"/css/shared.css?v=abc123"`): `FileMiddleware` ignores the query when
|
|
/// resolving the file, while caches key on the full URL, so a deploy that changes the assets busts every cached copy at once.
|
|
/// - Parameters:
|
|
/// - fileExtension: the extension of the file to resolve.
|
|
/// - version: the version token to append, or `nil` to leave the URL unversioned.
|
|
/// - Returns: the path to use in `href` and `src` attributes.
|
|
func urlPath(
|
|
for fileExtension: AssetExtension,
|
|
version: String? = nil
|
|
) -> String {
|
|
let path = "/\(relativePath(for: fileExtension))"
|
|
|
|
guard let version, !version.isEmpty else {
|
|
return path
|
|
}
|
|
|
|
return "\(path)?v=\(version)"
|
|
}
|
|
|
|
}
|