@modular-matrix/autodiscover-client-configuration

Automatically discovers the Matrix homeserver and identity server for a given hostname, according to the process described in the Client-Server API specification.

This module currently deviates from the specification in an important way: it also directly attempts to detect a homeserver running on the specified hostname, if none of the discovery methods in the specification were successful. As a lot of homeserver providers do not support the .well-known discovery method, this is necessary to make a Matrix client work in practice.

Part of the Modular Matrix toolkit, a set of modular libraries for working with the Matrix protocol.

Example

"use strict";

const Promise = require("bluebird");
const autodiscoverClientConfiguration = require("@modular-matrix/autodiscover-client-configuration");

return Promise.try(() => {
	return autodiscoverClientConfiguration.discover("pixie.town");
}).then((data) => {
	console.log(data);
	/*
	{ method: 'wellKnown',
	  homeserver: 'https://pixie.town',
	  identityServer: 'https://pixie.town',
	  raw: 
	   { 'm.homeserver': { base_url: 'https://pixie.town' },
	     'm.identity_server': { base_url: 'https://pixie.town' } } }
	*/
}).catch(autodiscoverClientConfiguration.LookupFailed, (error) => {
	console.error(error.message);
});

API

autodiscoverClientConfiguration.discover(hostname)

Attempt to determine the homeserver and identity server associated with the specified hostname.

• hostname: The hostname to apply autodiscovery for. This may be either an explicitly-specified hostname (not a URL!), or the hostname ("server name") extracted from a Matrix ID.

If no homeserver could be discovered, the returned Promise rejects with an autodiscoverClientConfiguration.LookupFailed error.

If the autodiscovery was successful, it will resolve with an object with the following structure:

• method: The method by which the homeserver information was determined. Currently one of wellKnown (using a .well-known/matrix/client file) or direct (connecting directly to the specified hostname).
• homeserver: The base URL of the autodiscovered homeserver.
• identityServer: Optional. The base URL of the identity server, if one was discovered.
• raw: Optional. The method-specific raw data that was used for autodiscovery. You don't need this unless you need to read out custom keys.
  • For wellKnown results, this data is the parsed response of .well-known/matrix/client.
  • For direct results, this property does not exist, as there is no raw data.

autodiscoverClientConfiguration.LookupFailed

An error type that signifies that this library could not determine a homeserver URL for the specified hostname.

This error type correctly inherits from Error, and can be used with instanceof and utilities that use it, such as Bluebird's filtered .catch.

Changelog

1.0.3 (August 31, 2019)

• Added missing Bluebird dependency to package.json (as a non-development dependency).

1.0.2 (August 31, 2019)

• DNS errors now also result in a LookupFailed error, like they should.

1.0.1 (August 30, 2019)

• Added input validation with an informative error to the discover method.

1.0.0 (August 30, 2019)

Initial release.