autodiscover-client-configuration/README.md

# @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](https://matrix.org/docs/spec/client_server/r0.5.0#server-discovery).

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](https://modular-matrix.cryto.net/) toolkit, a set of modular libraries for working with the [Matrix](https://matrix.org/) protocol.

## Example

```js
"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`](http://bluebirdjs.com/docs/api/catch.html#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.