fs/lib/adapters/AbstractAdapter.js

  1. import path from "node:path/posix";
  2. import {getLogger} from "@ui5/logger";
  3. const log = getLogger("resources:adapters:AbstractAdapter");
  4. import {minimatch} from "minimatch";
  5. import micromatch from "micromatch";
  6. import AbstractReaderWriter from "../AbstractReaderWriter.js";
  7. import Resource from "../Resource.js";
  9. /**
  10.  * Abstract Resource Adapter
  11.  *
  12.  * @abstract
  13.  * @public
  14.  * @class
  15.  * @alias @ui5/fs/adapters/AbstractAdapter
  16.  * @extends @ui5/fs/AbstractReaderWriter
  17.  */
  18. class AbstractAdapter extends AbstractReaderWriter {
  19. 	/**
  20. 	 * The constructor
  21. 	 *
  22. 	 * @public
  23. 	 * @param {object} parameters Parameters
  24. 	 * @param {string} parameters.virBasePath
  25. 	 *   Virtual base path. Must be absolute, POSIX-style, and must end with a slash
  26. 	 * @param {string[]} [parameters.excludes] List of glob patterns to exclude
  27. 	 * @param {object} [parameters.project] Experimental, internal parameter. Do not use
  28. 	 */
  29. 	constructor({virBasePath, excludes = [], project}) {
  30. 		if (new.target === AbstractAdapter) {
  31. 			throw new TypeError("Class 'AbstractAdapter' is abstract");
  32. 		}
  33. 		super();
  35. 		if (!virBasePath) {
  36. 			throw new Error(`Unable to create adapter: Missing parameter 'virBasePath'`);
  37. 		}
  38. 		if (!path.isAbsolute(virBasePath)) {
  39. 			throw new Error(`Unable to create adapter: Virtual base path must be absolute but is '${virBasePath}'`);
  40. 		}
  41. 		if (!virBasePath.endsWith("/")) {
  42. 			throw new Error(
  43. 				`Unable to create adapter: Virtual base path must end with a slash but is '${virBasePath}'`);
  44. 		}
  45. 		this._virBasePath = virBasePath;
  46. 		this._virBaseDir = virBasePath.slice(0, -1);
  47. 		this._excludes = excludes;
  48. 		this._excludesNegated = excludes.map((pattern) => `!${pattern}`);
  49. 		this._project = project;
  50. 	}
  51. 	/**
  52. 	 * Locates resources by glob.
  53. 	 *
  54. 	 * @abstract
  55. 	 * @private
  56. 	 * @param {string|string[]} virPattern glob pattern as string or an array of
  57. 	 *         glob patterns for virtual directory structure
  58. 	 * @param {object} [options={}] glob options
  59. 	 * @param {boolean} [options.nodir=true] Do not match directories
  60. 	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
  61. 	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
  62. 	 */
  63. 	async _byGlob(virPattern, options = {nodir: true}, trace) {
  64. 		const excludes = this._excludesNegated;
  66. 		if (!(virPattern instanceof Array)) {
  67. 			virPattern = [virPattern];
  68. 		}
  70. 		// Append static exclude patterns
  71. 		virPattern = Array.prototype.concat.apply(virPattern, excludes);
  72. 		let patterns = virPattern.map(this._normalizePattern, this);
  73. 		patterns = Array.prototype.concat.apply([], patterns);
  74. 		if (patterns.length === 0) {
  75. 			return [];
  76. 		}
  78. 		if (!options.nodir) {
  79. 			for (let i = patterns.length - 1; i >= 0; i--) {
  80. 				const idx = this._virBaseDir.indexOf(patterns[i]);
  81. 				if (patterns[i] && idx !== -1 && idx < this._virBaseDir.length) {
  82. 					const subPath = patterns[i];
  83. 					return [
  84. 						this._createResource({
  85. 							statInfo: { // TODO: make closer to fs stat info
  86. 								isDirectory: function() {
  87. 									return true;
  88. 								}
  89. 							},
  90. 							source: {
  91. 								adapter: "Abstract"
  92. 							},
  93. 							path: subPath
  94. 						})
  95. 					];
  96. 				}
  97. 			}
  98. 		}
  99. 		return await this._runGlob(patterns, options, trace);
  100. 	}
  102. 	/**
  103. 	 * Validate if virtual path should be excluded
  104. 	 *
  105. 	 * @param {string} virPath Virtual Path
  106. 	 * @returns {boolean} True if path is excluded, otherwise false
  107. 	 */
  108. 	_isPathExcluded(virPath) {
  109. 		return micromatch(virPath, this._excludes).length > 0;
  110. 	}
  112. 	/**
  113. 	 * Validate if virtual path should be handled by the adapter.
  114. 	 * This means that it either starts with the virtual base path of the adapter
  115. 	 * or equals the base directory (base path without a trailing slash)
  116. 	 *
  117. 	 * @param {string} virPath Virtual Path
  118. 	 * @returns {boolean} True if path should be handled
  119. 	 */
  120. 	_isPathHandled(virPath) {
  121. 		// Check whether path starts with base path, or equals base directory
  122. 		return virPath.startsWith(this._virBasePath) || virPath === this._virBaseDir;
  123. 	}
  125. 	/**
  126. 	 * Normalizes virtual glob patterns.
  127. 	 *
  128. 	 * @private
  129. 	 * @param {string} virPattern glob pattern for virtual directory structure
  130. 	 * @returns {string[]} A list of normalized glob patterns
  131. 	 */
  132. 	_normalizePattern(virPattern) {
  133. 		const that = this;
  134. 		const mm = new minimatch.Minimatch(virPattern);
  136. 		const basePathParts = this._virBaseDir.split("/");
  138. 		function matchSubset(subset) {
  139. 			let i;
  140. 			for (i = 0; i < basePathParts.length; i++) {
  141. 				const globPart = subset[i];
  142. 				if (globPart === undefined) {
  143. 					log.verbose("Ran out of glob parts to match (this should not happen):");
  144. 					if (that._project) { // project is optional
  145. 						log.verbose(`Project: ${that._project.getName()}`);
  146. 					}
  147. 					log.verbose(`Virtual base path: ${that._virBaseDir}`);
  148. 					log.verbose(`Pattern to match: ${virPattern}`);
  149. 					log.verbose(`Current subset (tried index ${i}):`);
  150. 					log.verbose(subset);
  151. 					return {idx: i, virtualMatch: true};
  152. 				}
  153. 				const basePathPart = basePathParts[i];
  154. 				if (typeof globPart === "string") {
  155. 					if (globPart !== basePathPart) {
  156. 						return null;
  157. 					} else {
  158. 						continue;
  159. 					}
  160. 				} else if (globPart === minimatch.GLOBSTAR) {
  161. 					return {idx: i};
  162. 				} else { // Regex
  163. 					if (!globPart.test(basePathPart)) {
  164. 						return null;
  165. 					} else {
  166. 						continue;
  167. 					}
  168. 				}
  169. 			}
  170. 			if (subset.length === basePathParts.length) {
  171. 				return {rootMatch: true};
  172. 			}
  173. 			return {idx: i};
  174. 		}
  176. 		const resultGlobs = [];
  177. 		for (let i = 0; i < mm.set.length; i++) {
  178. 			const match = matchSubset(mm.set[i]);
  179. 			if (match) {
  180. 				let resultPattern;
  181. 				if (match.virtualMatch) {
  182. 					resultPattern = basePathParts.slice(0, match.idx).join("/");
  183. 				} else if (match.rootMatch) { // matched one up
  184. 					resultPattern = ""; // root "/"
  185. 				} else { // matched at some part of the glob
  186. 					resultPattern = mm.globParts[i].slice(match.idx).join("/");
  187. 					if (resultPattern.startsWith("/")) {
  188. 						resultPattern = resultPattern.substr(1);
  189. 					}
  190. 				}
  191. 				if (mm.negate) {
  192. 					resultPattern = "!" + resultPattern;
  193. 				}
  194. 				resultGlobs.push(resultPattern);
  195. 			}
  196. 		}
  197. 		return resultGlobs;
  198. 	}
  200. 	_createResource(parameters) {
  201. 		if (this._project) {
  202. 			parameters.project = this._project;
  203. 		}
  204. 		return new Resource(parameters);
  205. 	}
  207. 	_migrateResource(resource) {
  208. 		// This function only returns a promise if a migration is necessary.
  209. 		// Since this is rarely the case, we therefore reduce the amount of
  210. 		// created Promises by making this differentiation
  212. 		// Check if its a fs/Resource v3, function 'hasProject' was
  213. 		// introduced with v3 therefore take it as the indicator
  214. 		if (resource.hasProject) {
  215. 			return resource;
  216. 		}
  217. 		return this._createFromLegacyResource(resource);
  218. 	}
  220. 	async _createFromLegacyResource(resource) {
  221. 		const options = {
  222. 			path: resource._path,
  223. 			statInfo: resource._statInfo,
  224. 			source: resource._source
  225. 		};
  227. 		if (resource._stream) {
  228. 			options.buffer = await resource._getBufferFromStream();
  229. 		} else if (resource._createStream) {
  230. 			options.createStream = resource._createStream;
  231. 		} else if (resource._buffer) {
  232. 			options.buffer = resource._buffer;
  233. 		}
  234. 		return new Resource(options);
  235. 	}
  237. 	_assignProjectToResource(resource) {
  238. 		if (this._project) {
  239. 			// Assign project to resource if necessary
  240. 			if (resource.hasProject()) {
  241. 				if (resource.getProject() !== this._project) {
  242. 					throw new Error(
  243. 						`Unable to write resource associated with project ` +
  244. 						`${resource.getProject().getName()} into adapter of project ${this._project.getName()}: ` +
  245. 						resource.getPath());
  246. 				}
  247. 				return;
  248. 			}
  249. 			log.silly(`Associating resource ${resource.getPath()} with project ${this._project.getName()}`);
  250. 			resource.setProject(this._project);
  251. 		}
  252. 	}
  254. 	_resolveVirtualPathToBase(inputVirPath, writeMode = false) {
  255. 		if (!path.isAbsolute(inputVirPath)) {
  256. 			throw new Error(`Failed to resolve virtual path '${inputVirPath}': Path must be absolute`);
  257. 		}
  258. 		// Resolve any ".." segments to make sure we compare the effective start of the path
  259. 		// with the virBasePath
  260. 		const virPath = path.normalize(inputVirPath);
  262. 		if (!writeMode) {
  263. 			// When reading resources, validate against path excludes and return null if the given path
  264. 			// does not match this adapters base path
  265. 			if (!this._isPathHandled(virPath)) {
  266. 				if (log.isLevelEnabled("silly")) {
  267. 					log.silly(`Failed to resolve virtual path '${inputVirPath}': ` +
  268. 						`Resolved path does not start with adapter base path '${this._virBasePath}' or equals ` +
  269. 						`base dir: ${this._virBaseDir}`);
  270. 				}
  271. 				return null;
  272. 			}
  273. 			if (this._isPathExcluded(virPath)) {
  274. 				if (log.isLevelEnabled("silly")) {
  275. 					log.silly(`Failed to resolve virtual path '${inputVirPath}': ` +
  276. 						`Resolved path is excluded by configuration of adapter with base path '${this._virBasePath}'`);
  277. 				}
  278. 				return null;
  279. 			}
  280. 		} else if (!this._isPathHandled(virPath)) {
  281. 			// Resolved path is not within the configured base path and does
  282. 			// not equal the virtual base directory.
  283. 			// Since we don't want to write resources to foreign locations, we throw an error
  284. 			throw new Error(
  285. 				`Failed to write resource with virtual path '${inputVirPath}': Path must start with ` +
  286. 				`the configured virtual base path of the adapter. Base path: '${this._virBasePath}'`);
  287. 		}
  289. 		const relPath = virPath.substr(this._virBasePath.length);
  290. 		return relPath;
  291. 	}
  292. }
  294. export default AbstractAdapter;