Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2025-03-10 23:01:26 -05:00
Code Issues Activity

docs: document asset utilities (#13355)

Browse source 
* docs: document asset utilities

* Apply suggestions from code review

Co-authored-by: Junseong Park <39112954+jsparkdev@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

* chore: add defaults

* chore: add changeset

---------

Co-authored-by: Junseong Park <39112954+jsparkdev@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
This commit is contained in:
Emanuele Stoppa 2025-03-05 08:16:39 +00:00 • committed by GitHub
parent c67a35138c
commit 042d1de901
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 58 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.changeset/metal-tomatoes-confess.md Normal file
View file

@ -0,0 +1,6 @@
---
'@astrojs/internal-helpers': patch
'astro': patch
---
Adds documentation to the assets utilities for remote service images.

57
packages/internal-helpers/src/remote.ts
View file

@ -5,7 +5,14 @@ export type RemotePattern = {
port?: string;
};
export function matchPattern(url: URL, remotePattern: RemotePattern) {
/**
* Evaluates whether a given URL matches the specified remote pattern based on protocol, hostname, port, and pathname.
*
* @param {URL} url - The URL object to be matched against the remote pattern.
* @param {RemotePattern} remotePattern - The remote pattern object containing the protocol, hostname, port, and pathname to match.
* @return {boolean} Returns `true` if the URL matches the given remote pattern; otherwise, `false`.
*/
export function matchPattern(url: URL, remotePattern: RemotePattern): boolean {
return (
matchProtocol(url, remotePattern.protocol) &&
matchHostname(url, remotePattern.hostname, true) &&
@ -14,15 +21,37 @@ export function matchPattern(url: URL, remotePattern: RemotePattern) {
);
}
export function matchPort(url: URL, port?: string) {
/**
* Checks if the given URL's port matches the specified port. If no port is provided, it returns `true`.
*
* @param {URL} url - The URL object whose port will be checked.
* @param {string} [port=] - The port to match against the URL's port. Optional.
* @return {boolean} Returns `true` if the URL's port matches the specified port or if no port is provided; otherwise, `false`.
*/
export function matchPort(url: URL, port?: string): boolean {
return !port || port === url.port;
}
export function matchProtocol(url: URL, protocol?: string) {
/**
* Compares the protocol of the provided URL with a specified protocol.
*
* @param {URL} url - The URL object whose protocol needs to be checked.
* @param {string} [protocol] - The protocol to compare against, without the trailing colon. If not provided, the method will always return `true`.
* @return {boolean} Returns `true` if the protocol matches or if no protocol is specified; otherwise, `false`.
*/
export function matchProtocol(url: URL, protocol?: string): boolean {
return !protocol || protocol === url.protocol.slice(0, -1);
}
export function matchHostname(url: URL, hostname?: string, allowWildcard?: boolean) {
/**
* Matches a given URL's hostname against a specified hostname, with optional support for wildcard patterns.
*
* @param {URL} url - The URL object whose hostname is to be matched.
* @param {string} [hostname] - The hostname to match against. Supports wildcard patterns if `allowWildcard` is `true`.
* @param {boolean} [allowWildcard=false] - Indicates whether wildcard patterns in the `hostname` parameter are allowed.
* @return {boolean} - Returns `true` if the URL's hostname matches the given hostname criteria; otherwise, `false`.
*/
export function matchHostname(url: URL, hostname?: string, allowWildcard = false): boolean {
if (!hostname) {
return true;
} else if (!allowWildcard || !hostname.startsWith('*')) {
@ -42,7 +71,15 @@ export function matchHostname(url: URL, hostname?: string, allowWildcard?: boole
return false;
}
export function matchPathname(url: URL, pathname?: string, allowWildcard?: boolean) {
/**
* Matches a given URL's pathname against a specified pattern, with optional support for wildcards.
*
* @param {URL} url - The URL object containing the pathname to be matched.
* @param {string} [pathname] - The pathname pattern to match the URL against.
* @param {boolean} [allowWildcard=false] - Determines whether wildcard matching is allowed.
* @return {boolean} - Returns `true` if the URL's pathname matches the specified pattern; otherwise, `false`.
*/
export function matchPathname(url: URL, pathname?: string, allowWildcard = false): boolean {
if (!pathname) {
return true;
} else if (!allowWildcard || !pathname.endsWith('*')) {
@ -62,6 +99,16 @@ export function matchPathname(url: URL, pathname?: string, allowWildcard?: boole
return false;
}
/**
* Determines whether a given remote resource, identified by its source URL,
* is allowed based on specified domains and remote patterns.
*
* @param {string} src - The source URL of the remote resource to be validated.
* @param {Object} options - The configuration options for domain and pattern matching.
* @param {string[]} options.domains - A list of allowed domain names.
* @param {RemotePattern[]} options.remotePatterns - A list of allowed remote patterns for matching.
* @return {boolean} Returns `true` if the source URL matches any of the specified domains or remote patterns; otherwise, `false`.
*/
export function isRemoteAllowed(
src: string,
{