You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# @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.
|