@loaders.gl/wms 3.3.2 → 3.4.0-alpha.2

package/src/lib/services/ogc/csw-service.ts

@@ -0,0 +1,251 @@
+// loaders.gl, MIT license
+
+/* eslint-disable camelcase */
+
+import type {DataSourceProps} from '../../sources/data-source';
+import {DataSource} from '../../sources/data-source';
+
+import type {CSWCapabilities} from '../../../csw-capabilities-loader';
+import {CSWCapabilitiesLoader} from '../../../csw-capabilities-loader';
+
+import type {CSWRecords} from '../../../csw-records-loader';
+import {CSWRecordsLoader} from '../../../csw-records-loader';
+
+import type {CSWDomain} from '../../../csw-domain-loader';
+import {CSWDomainLoader} from '../../../csw-domain-loader';
+
+import {WMSErrorLoader as CSWErrorLoader} from '../../../wms-error-loader';
+
+type CSWCommonParameters = {
+  /** In case the endpoint supports multiple services */
+  service?: 'CSW';
+  /** In case the endpoint supports multiple CSW versions */
+  version?: '1.1.1' | '2.0.0' | '2.0.1' | '3.0.0' | '3.0.0';
+};
+
+export type CSWGetCapabilitiesParameters = CSWCommonParameters & {
+  /** Request type */
+  request?: 'GetCapabilities';
+};
+
+export type CSWGetRecordsParameters = CSWCommonParameters & {
+  /** Request type */
+  request?: 'GetRecords';
+  /** type of records */
+  typenames: 'csw:Record';
+};
+
+export type CSWGetDomainParameters = CSWCommonParameters & {
+  /** Request type */
+  request?: 'GetDomain';
+  // TBA
+};
+
+export type Service = {name: string; type: string; url: string; params?: string; scheme?: string};
+
+export type CSWServiceProps = DataSourceProps & {
+  url: string;
+};
+
+/**
+ * The CSWService class provides
+ * - provides type safe methods to form URLs to a CSW service
+ * - provides type safe methods to query and parse results (and errors) from a CSW service
+ * - implements the ImageService interface
+ * @note Only the URL parameter conversion is supported. XML posts are not supported.
+ */
+export class CSWService extends DataSource {
+  static type: 'csw' = 'csw';
+  static testURL = (url: string): boolean => url.toLowerCase().includes('csw');
+
+  props: CSWServiceProps;
+  capabilities: CSWCapabilities | null = null;
+
+  /** A list of loaders used by the CSWService methods */
+  readonly loaders = [CSWErrorLoader, CSWCapabilitiesLoader];
+
+  /** Create a CSWService */
+  constructor(props: CSWServiceProps) {
+    super(props);
+    this.props = props;
+  }
+
+  async getMetadata(): Promise<CSWCapabilities> {
+    const capabilities = await this.getCapabilities();
+    return this.normalizeMetadata(capabilities);
+  }
+
+  normalizeMetadata(capabilities: CSWCapabilities): CSWCapabilities {
+    return capabilities;
+  }
+
+  async getServiceDirectory(options: {includeUnknown?: boolean}): Promise<Service[]> {
+    const services: Service[] = [];
+    const unknownServices: Service[] = [];
+
+    const records = await this.getRecords();
+    for (const record of records.records) {
+      for (const reference of record.references) {
+        const url = reference.value;
+        switch (reference.scheme) {
+          case 'OGC:WMS':
+            services.push({name: record.title, type: 'ogc-wms-service', ...this._parseOGCUrl(url)});
+            break;
+          case 'OGC:WMTS':
+            services.push({
+              name: record.title,
+              type: 'ogc-wmts-service',
+              ...this._parseOGCUrl(url)
+            });
+            break;
+          case 'OGC:WFS':
+            services.push({name: record.title, type: 'ogc-wfs-service', ...this._parseOGCUrl(url)});
+            break;
+          default:
+            unknownServices.push({
+              name: record.title,
+              type: 'unknown',
+              url: reference.value,
+              scheme: reference.scheme
+            });
+        }
+      }
+    }
+
+    return options?.includeUnknown ? services.concat(unknownServices) : services;
+  }
+
+  _parseOGCUrl(url: string): {url: string; params: string} {
+    const parts = url.split('?');
+    return {
+      url: parts[0],
+      params: parts[1] || ''
+    };
+  }
+
+  // CSW Service API Stubs
+
+  /** Get Capabilities */
+  async getCapabilities(
+    wmsParameters?: CSWGetCapabilitiesParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<CSWCapabilities> {
+    const url = this.getCapabilitiesURL(wmsParameters, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    const capabilities = await CSWCapabilitiesLoader.parse(arrayBuffer, this.props.loadOptions);
+    return capabilities;
+  }
+
+  /** Get Records */
+  async getRecords(
+    wmsParameters?: CSWGetRecordsParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<CSWRecords> {
+    const url = this.getRecordsURL(wmsParameters, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return await CSWRecordsLoader.parse(arrayBuffer, this.props.loadOptions);
+  }
+
+  /** Get Domain */
+  async getDomain(
+    wmsParameters?: CSWGetDomainParameters,
+    vendorParameters?: Record<string, unknown>
+  ): Promise<CSWDomain> {
+    const url = this.getDomainURL(wmsParameters, vendorParameters);
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return await CSWDomainLoader.parse(arrayBuffer, this.props.loadOptions);
+  }
+
+  // Typed URL creators
+  // For applications that want full control of fetching and parsing
+
+  /** Generate a URL for the GetCapabilities request */
+  getCapabilitiesURL(
+    wmsParameters?: CSWGetCapabilitiesParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<CSWGetCapabilitiesParameters> = {
+      version: '3.0.0',
+      ...wmsParameters,
+      ...vendorParameters,
+      service: 'CSW',
+      request: 'GetCapabilities'
+    };
+    return this._getCSWUrl(options, vendorParameters);
+  }
+
+  /** Generate a URL for the GetCapabilities request */
+  getRecordsURL(
+    wmsParameters?: CSWGetRecordsParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<CSWGetRecordsParameters> = {
+      version: '3.0.0',
+      typenames: 'csw:Record',
+      ...wmsParameters,
+      ...vendorParameters,
+      service: 'CSW',
+      request: 'GetRecords'
+    };
+    return this._getCSWUrl(options, vendorParameters);
+  }
+
+  /** Generate a URL for the GetCapabilities request */
+  getDomainURL(
+    wmsParameters?: CSWGetDomainParameters,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    const options: Required<CSWGetDomainParameters> = {
+      version: '3.0.0',
+      ...wmsParameters,
+      ...vendorParameters,
+      service: 'CSW',
+      request: 'GetDomain'
+    };
+    return this._getCSWUrl(options, vendorParameters);
+  }
+
+  // INTERNAL METHODS
+
+  /**
+   * @note case _getCSWUrl may need to be overridden to handle certain backends?
+   * */
+  protected _getCSWUrl(
+    options: Record<string, unknown>,
+    vendorParameters?: Record<string, unknown>
+  ): string {
+    let url = this.props.url;
+    let first = true;
+    for (const [key, value] of Object.entries(options)) {
+      url += first ? '?' : '&';
+      first = false;
+      if (Array.isArray(value)) {
+        url += `${key.toUpperCase()}=${value.join(',')}`;
+      } else {
+        url += `${key.toUpperCase()}=${value ? String(value) : ''}`;
+      }
+    }
+    return encodeURI(url);
+  }
+
+  /** Checks for and parses a CSW XML formatted ServiceError and throws an exception */
+  protected _checkResponse(response: Response, arrayBuffer: ArrayBuffer): void {
+    const contentType = response.headers['content-type'];
+    if (!response.ok || CSWErrorLoader.mimeTypes.includes(contentType)) {
+      const error = CSWErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+      throw new Error(error);
+    }
+  }
+
+  /** Error situation detected */
+  protected _parseError(arrayBuffer: ArrayBuffer): Error {
+    const error = CSWErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+    return new Error(error);
+  }
+}

package/src/lib/{data-sources/image-services → services/ogc}/wms-service.ts

@@ -4,15 +4,21 @@
 
 import type {ImageType} from '@loaders.gl/images';
 import {ImageLoader} from '@loaders.gl/images';
+import {mergeLoaderOptions} from '@loaders.gl/loader-utils';
 
-import type {ImageSourceMetadata, GetImageParameters} from '../image-source';
-import {ImageSource} from '../image-source';
-import {ImageServiceProps, getFetchFunction, mergeImageServiceProps} from './image-service';
+import type {ImageSourceMetadata, GetImageParameters} from '../../sources/image-source';
+import type {ImageSourceProps} from '../../sources/image-source';
+import {ImageSource} from '../../sources/image-source';
+
+import type {WMSCapabilities} from '../../../wms-capabilities-loader';
+import type {WMSFeatureInfo} from '../../../wip/wms-feature-info-loader';
+import type {WMSLayerDescription} from '../../../wip/wms-layer-description-loader';
 
-import type {WMSCapabilities, WMSFeatureInfo, WMSLayerDescription} from '../../wms/wms-types';
 import {WMSCapabilitiesLoader} from '../../../wms-capabilities-loader';
 import {WMSFeatureInfoLoader} from '../../../wip/wms-feature-info-loader';
 import {WMSLayerDescriptionLoader} from '../../../wip/wms-layer-description-loader';
+
+import type {WMSLoaderOptions} from '../../../wms-error-loader';
 import {WMSErrorLoader} from '../../../wms-error-loader';
 
 type WMSCommonParameters = {
@@ -57,7 +63,7 @@ export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
   y: number;
   /** list of layers to query (could be different from rendered layers) */
   query_layers: string[];
-  /** MIME type of returned feature info */
+  /** Requested MIME type of returned feature info */
   info_format?: 'text/plain' | 'application/vnd.ogc.gml';
 
   /** Layers to render */
@@ -86,6 +92,24 @@ export type WMSGetLegendGraphicParameters = WMSCommonParameters & {
   request?: 'GetLegendGraphic';
 };
 
+/** Properties for initializing a WMS service */
+export type WMSServiceProps = ImageSourceProps & {
+  /** Base URL to the service */
+  url: string;
+  /** WMS version */
+  version?: '1.1.1' | '1.3.0';
+  /** Layers to render */
+  layers?: string[];
+  /** SRS for the image (not the bounding box) */
+  srs?: string;
+  /** Requested format for the return image */
+  format?: 'image/png';
+  /** Requested MIME type of returned feature info */
+  info_format?: 'text/plain' | 'application/vnd.ogc.gml';
+  /** Styling */
+  styles?: unknown;
+};
+
 /**
  * The WMSService class provides
  * - provides type safe methods to form URLs to a WMS service
@@ -97,8 +121,7 @@ export class WMSService extends ImageSource {
   static type: 'wms' = 'wms';
   static testURL = (url: string): boolean => url.toLowerCase().includes('wms');
 
-  props: Required<ImageServiceProps>;
-  fetch: (url: string, options?: RequestInit) => Promise<Response>;
+  props: Required<WMSServiceProps>;
   capabilities: WMSCapabilities | null = null;
 
   /** A list of loaders used by the WMSService methods */
@@ -111,24 +134,36 @@ export class WMSService extends ImageSource {
   ];
 
   /** Create a WMSService */
-  constructor(props: ImageServiceProps) {
-    super();
-    this.props = mergeImageServiceProps(props);
-    this.fetch = getFetchFunction(this.props);
-    this.props.loadOptions = {
-      ...this.props.loadOptions,
-      // We want error responses to throw exceptions, the WMSErrorLoader can do this
-      wms: {...this.props.loadOptions?.wms, throwOnError: true}
+  constructor(props: WMSServiceProps) {
+    super(props);
+
+    // TODO - defaults such as version, layers etc could be extracted from a base URL with parameters
+    // This would make pasting in any WMS URL more likely to make this class just work.
+
+    this.props = {
+      loadOptions: undefined!,
+      layers: undefined!,
+      styles: undefined,
+      version: '1.1.1',
+      srs: 'EPSG:4326',
+      format: 'image/png',
+      info_format: 'text/plain',
+      ...props
     };
   }
 
   // ImageSource implementation
-  getMetadata(): Promise<ImageSourceMetadata> {
-    return this.getCapabilities();
+  async getMetadata(): Promise<ImageSourceMetadata> {
+    const capabilities = await this.getCapabilities();
+    return this.normalizeMetadata(capabilities);
   }
 
-  getImage(parameters: GetImageParameters): Promise<ImageType> {
-    return this.getMap(parameters);
+  async getImage(parameters: GetImageParameters): Promise<ImageType> {
+    return await this.getMap(parameters);
+  }
+
+  normalizeMetadata(capabilities: WMSCapabilities): ImageSourceMetadata {
+    return capabilities;
   }
 
   // WMS Service API Stubs
@@ -180,7 +215,6 @@ export class WMSService extends ImageSource {
     options: WMSGetFeatureInfoParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<string> {
-    options = {...options, info_format: 'text/plain'};
     const url = this.getFeatureInfoURL(options, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
@@ -226,7 +260,7 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSGetCapabilitiesParameters> = {
       service: 'WMS',
-      version: '1.1.1',
+      version: this.props.version,
       request: 'GetCapabilities',
       ...wmsParameters,
       ...vendorParameters
@@ -241,15 +275,15 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSGetMapParameters> = {
       service: 'WMS',
-      version: '1.1.1',
+      version: this.props.version,
       request: 'GetMap',
       // layers: [],
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
-      styles: undefined,
-      srs: 'EPSG:4326',
-      format: 'image/png',
+      styles: this.props.styles,
+      srs: this.props.srs,
+      format: this.props.format,
       ...wmsParameters,
       ...vendorParameters
     };
@@ -263,19 +297,19 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSGetFeatureInfoParameters> = {
       service: 'WMS',
-      version: '1.1.1',
+      version: this.props.version,
       request: 'GetFeatureInfo',
-      // layers: [],
+      // layers: this.props.layers,
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
       // x: undefined!,
       // y: undefined!,
       // query_layers: [],
-      srs: 'EPSG:4326',
-      format: 'image/png',
-      info_format: 'text/plain',
-      styles: undefined,
+      srs: this.props.srs,
+      format: this.props.format,
+      info_format: this.props.info_format,
+      styles: this.props.styles,
       ...wmsParameters,
       ...vendorParameters
     };
@@ -289,7 +323,7 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSDescribeLayerParameters> = {
       service: 'WMS',
-      version: '1.1.1',
+      version: this.props.version,
       request: 'DescribeLayer',
       ...wmsParameters,
       ...vendorParameters
@@ -303,8 +337,9 @@ export class WMSService extends ImageSource {
   ): string {
     const options: Required<WMSGetLegendGraphicParameters> = {
       service: 'WMS',
-      version: '1.1.1',
+      version: this.props.version,
       request: 'GetLegendGraphic',
+      // format?
       ...wmsParameters,
       ...vendorParameters
     };
@@ -338,7 +373,11 @@ export class WMSService extends ImageSource {
   protected _checkResponse(response: Response, arrayBuffer: ArrayBuffer): void {
     const contentType = response.headers['content-type'];
     if (!response.ok || WMSErrorLoader.mimeTypes.includes(contentType)) {
-      const error = WMSErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+      // We want error responses to throw exceptions, the WMSErrorLoader can do this
+      const loadOptions = mergeLoaderOptions<WMSLoaderOptions>(this.props.loadOptions, {
+        wms: {throwOnError: true}
+      });
+      const error = WMSErrorLoader.parseSync(arrayBuffer, loadOptions);
       throw new Error(error);
     }
   }