server/lib/middleware/MiddlewareUtil.js

  1. import parseurl from "parseurl";
  2. import mime from "mime-types";
  3. import {
  4. 	createReaderCollection,
  5. 	createReaderCollectionPrioritized,
  6. 	createResource,
  7. 	createFilterReader,
  8. 	createLinkReader,
  9. 	createFlatReader
  10. } from "@ui5/fs/resourceFactory";
  12. /**
  13.  * Convenience functions for UI5 Server middleware.
  14.  * An instance of this class is passed to every standard UI5 Server middleware.
  15.  * Custom middleware that define a specification version >= 2.0 will also receive an instance
  16.  * of this class as part of the parameters of their create-middleware function.
  17.  *
  18.  * The set of functions that can be accessed by a custom middleware depends on the specification
  19.  * version defined for the extension.
  20.  *
  21.  * @public
  22.  * @class
  23.  * @alias @ui5/server/middleware/MiddlewareUtil
  24.  * @hideconstructor
  25.  */
  26. class MiddlewareUtil {
  27. 	/**
  28. 	 *
  29. 	 * @param {object} parameters
  30. 	 * @param {@ui5/project/graph/ProjectGraph} parameters.graph Relevant ProjectGraph
  31. 	 * @param {@ui5/project/specifications/Project} parameters.project Project that is being served
  32. 	 * @public
  33. 	 */
  34. 	constructor({graph, project}) {
  35. 		if (!graph) {
  36. 			throw new Error(`Missing parameter "graph"`);
  37. 		}
  38. 		if (!project) {
  39. 			throw new Error(`Missing parameter "project"`);
  40. 		}
  41. 		this._graph = graph;
  42. 		this._project = project;
  43. 	}
  45. 	/**
  46. 	 * Returns the [pathname]{@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname}
  47. 	 * of a given request. Any escape sequences will be decoded.
  48. 	 * </br></br>
  49. 	 * This method is only available to custom middleware extensions defining
  50. 	 * <b>Specification Version 2.0 and above</b>.
  51. 	 *
  52. 	 * @param {object} req Request object
  53. 	 * @returns {string} [Pathname]{@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname}
  54. 	 * of the given request
  55. 	 * @public
  56. 	 */
  57. 	getPathname(req) {
  58. 		let {pathname} = parseurl(req);
  59. 		pathname = decodeURIComponent(pathname);
  60. 		return pathname;
  61. 	}
  63. 	/**
  64. 	 * MIME Info
  65. 	 *
  66. 	 * @example
  67. 	 * const mimeInfo = {
  68. 	 * 	"type": "text/html",
  69. 	 * 	"charset": "utf-8",
  70. 	 * 	"contentType": "text/html; charset=utf-8"
  71. 	 * };
  72. 	 *
  73. 	 * @public
  74. 	 * @typedef {object} MimeInfo
  75. 	 * @property {string} type Detected content-type for the given resource path
  76. 	 * @property {string} charset Default charset for the detected content-type
  77. 	 * @property {string} contentType Calculated content-type header value
  78. 	 * @memberof @ui5/server/middleware/MiddlewareUtil
  79. 	 */
  80. 	/**
  81. 	 * Returns MIME information derived from a given resource path.
  82. 	 * </br></br>
  83. 	 * This method is only available to custom middleware extensions defining
  84. 	 * <b>Specification Version 2.0 and above</b>.
  85. 	 *
  86. 	 * @param {object} resourcePath
  87. 	 * @returns {@ui5/server/middleware/MiddlewareUtil.MimeInfo}
  88. 	 * @public
  89. 	 */
  90. 	getMimeInfo(resourcePath) {
  91. 		const type = mime.lookup(resourcePath) || "application/octet-stream";
  92. 		const charset = mime.charset(type);
  93. 		return {
  94. 			type,
  95. 			charset,
  96. 			contentType: type + (charset ? "; charset=" + charset : "")
  97. 		};
  98. 	}
  99. 	/**
  100. 	 * Specification Version-dependent [Project]{@link @ui5/project/specifications/Project} interface.
  101. 	 * For details on individual functions, see [Project]{@link @ui5/project/specifications/Project}
  102. 	 *
  103. 	 * @public
  104. 	 * @typedef {object} @ui5/server/middleware/MiddlewareUtil~ProjectInterface
  105. 	 * @property {Function} getType Get the project type
  106. 	 * @property {Function} getName Get the project name
  107. 	 * @property {Function} getVersion Get the project version
  108. 	 * @property {Function} getNamespace Get the project namespace
  109. 	 * @property {Function} getRootReader Get the project rootReader
  110. 	 * @property {Function} getReader Get the project reader, defaulting to "runtime" style instead of "buildtime"
  111. 	 * @property {Function} getRootPath Get the local File System path of the project's root directory
  112. 	 * @property {Function} getSourcePath Get the local File System path of the project's source directory
  113. 	 * @property {Function} getCustomConfiguration Get the project Custom Configuration
  114. 	 * @property {Function} isFrameworkProject Check whether the project is a UI5-Framework project
  115. 	 * @property {Function} getFrameworkName Get the project's framework name configuration
  116. 	 * @property {Function} getFrameworkVersion Get the project's framework version configuration
  117. 	 * @property {Function} getFrameworkDependencies Get the project's framework dependencies configuration
  118. 	 */
  120. 	/**
  121. 	 * Retrieve a single project from the dependency graph
  122. 	 *
  123. 	 * </br></br>
  124. 	 * This method is only available to custom server middleware extensions defining
  125. 	 * <b>Specification Version 3.0 and above</b>.
  126. 	 *
  127. 	 * @param {string|@ui5/fs/Resource} [projectNameOrResource]
  128. 	 * Name of the project to retrieve or a Resource instance to retrieve the associated project for.
  129. 	 * Defaults to the name of the current root project
  130. 	 * @returns {@ui5/server/middleware/MiddlewareUtil~ProjectInterface|undefined}
  131. 	 * Specification Version-dependent interface to the Project instance or <code>undefined</code>
  132. 	 * if the project name is unknown or the provided resource is not associated with any project.
  133. 	 * @public
  134. 	 */
  135. 	getProject(projectNameOrResource) {
  136. 		if (projectNameOrResource) {
  137. 			if (typeof projectNameOrResource === "string" || projectNameOrResource instanceof String) {
  138. 				// A project name has been provided
  139. 				return this._graph.getProject(projectNameOrResource);
  140. 			} else {
  141. 				// A Resource instance has been provided
  142. 				return projectNameOrResource.getProject();
  143. 			}
  144. 		}
  145. 		// No parameter has been provided, default to the root project
  146. 		return this._project;
  147. 	}
  149. 	/**
  150. 	 * Retrieve a list of direct dependencies of a given project from the dependency graph.
  151. 	 * Note that this list does not include transitive dependencies.
  152. 	 *
  153. 	 * </br></br>
  154. 	 * This method is only available to custom server middleware extensions defining
  155. 	 * <b>Specification Version 3.0 and above</b>.
  156. 	 *
  157. 	 * @param {string} [projectName] Name of the project to retrieve.
  158. 	 * Defaults to the name of the current root project
  159. 	 * @returns {string[]} Names of all direct dependencies
  160. 	 * @throws {Error} If the requested project is unknown to the graph
  161. 	 * @public
  162. 	 */
  163. 	getDependencies(projectName) {
  164. 		return this._graph.getDependencies(projectName || this._project.getName());
  165. 	}
  167. 	/**
  168. 	 * Specification Version-dependent set of [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory}
  169. 	 * functions provided to middleware.
  170. 	 * For details on individual functions, see [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory}
  171. 	 *
  172. 	 * @public
  173. 	 * @typedef {object} @ui5/server/middleware/MiddlewareUtil~resourceFactory
  174. 	 * @property {Function} createResource Creates a [Resource]{@link @ui5/fs/Resource}.
  175. 	 * 	Accepts the same parameters as the [Resource]{@link @ui5/fs/Resource} constructor.
  176. 	 * @property {Function} createReaderCollection Creates a reader collection:
  177. 	 *	[ReaderCollection]{@link @ui5/fs/ReaderCollection}
  178. 	 * @property {Function} createReaderCollectionPrioritized Creates a prioritized reader collection:
  179. 	 *	[ReaderCollectionPrioritized]{@link @ui5/fs/ReaderCollectionPrioritized}
  180. 	 * @property {Function} createFilterReader
  181. 	 * 	Create a [Filter-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  182. 	 * @property {Function} createLinkReader
  183. 	 * 	Create a [Link-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  184. 	 * @property {Function} createFlatReader Create a [Link-Reader]{@link @ui5/fs/readers/Link}
  185. 	 * where all requests are prefixed with <code>/resources/<namespace></code>.
  186. 	 */
  188. 	/**
  189. 	 * Provides limited access to [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory} functions
  190. 	 *
  191. 	 * </br></br>
  192. 	 * This attribute is only available to custom server middleware extensions defining
  193. 	 * <b>Specification Version 3.0 and above</b>.
  194. 	 *
  195. 	 * @type {@ui5/server/middleware/MiddlewareUtil~resourceFactory}
  196. 	 * @public
  197. 	 */
  198. 	resourceFactory = {
  199. 		createResource,
  200. 		createReaderCollection,
  201. 		createReaderCollectionPrioritized,
  202. 		createFilterReader,
  203. 		createLinkReader,
  204. 		createFlatReader,
  205. 	};
  207. 	/**
  208. 	 * Get an interface to an instance of this class that only provides those functions
  209. 	 * that are supported by the given custom middleware extension specification version.
  210. 	 *
  211. 	 * @param {@ui5/project/specifications/SpecificationVersion} specVersion
  212. 	 * SpecVersionComparator instance of the custom server middleware
  213. 	 * @returns {object} An object with bound instance methods supported by the given specification version
  214. 	 */
  215. 	getInterface(specVersion) {
  216. 		if (specVersion.lt("2.0")) {
  217. 			// Custom middleware defining specVersion <2.0 does not have access to any MiddlewareUtil API
  218. 			return undefined;
  219. 		}
  221. 		const baseInterface = {};
  222. 		bindFunctions(this, baseInterface, [
  223. 			"getPathname", "getMimeInfo"
  224. 		]);
  226. 		if (specVersion.gte("3.0")) {
  227. 			// getProject function, returning an interfaced project instance
  228. 			baseInterface.getProject = (projectName) => {
  229. 				const project = this.getProject(projectName);
  230. 				const baseProjectInterface = {};
  231. 				bindFunctions(project, baseProjectInterface, [
  232. 					"getType", "getName", "getVersion", "getNamespace",
  233. 					"getRootReader", "getRootPath", "getSourcePath",
  234. 					"getCustomConfiguration", "isFrameworkProject", "getFrameworkName",
  235. 					"getFrameworkVersion", "getFrameworkDependencies"
  236. 				]);
  237. 				// Project#getReader defaults to style "buildtime". However ui5-server uses
  238. 				// style "runtime". The main difference is that for some project types (like applications)
  239. 				// the /resources/<namespace> path prefix is omitted for "runtime". Also, no builder resource-
  240. 				// exclude configuration is applied.
  241. 				// Therefore default to style "runtime" here so that custom middleware will commonly work with
  242. 				// the same paths as ui5-server and no unexpected builder-excludes.
  243. 				baseProjectInterface.getReader = function(options = {style: "runtime"}) {
  244. 					return project.getReader(options);
  245. 				};
  246. 				return baseProjectInterface;
  247. 			};
  248. 			// getDependencies function, returning an array of project names
  249. 			baseInterface.getDependencies = (projectName) => {
  250. 				return this.getDependencies(projectName);
  251. 			};
  253. 			baseInterface.resourceFactory = Object.create(null);
  254. 			[
  255. 				// Once new functions get added, extract this array into a variable
  256. 				// and enhance based on spec version once new functions get added
  257. 				"createResource", "createReaderCollection", "createReaderCollectionPrioritized",
  258. 				"createFilterReader", "createLinkReader", "createFlatReader",
  259. 			].forEach((factoryFunction) => {
  260. 				baseInterface.resourceFactory[factoryFunction] = this.resourceFactory[factoryFunction];
  261. 			});
  262. 		}
  263. 		return baseInterface;
  264. 	}
  265. }
  267. function bindFunctions(sourceObject, targetObject, funcNames) {
  268. 	funcNames.forEach((funcName) => {
  269. 		targetObject[funcName] = sourceObject[funcName].bind(sourceObject);
  270. 	});
  271. }
  273. export default MiddlewareUtil;