@modular-matrix/autodiscover-server-configuration
forked from autodiscover-client-configuration which is what you need for client-server API discovery.
Automatically discovers the Matrix homeserver for a given hostname, according to the process described in the Server-Server API specification.
(not yet) 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 autodiscoverServerConfiguration = require("@f0x52/autodiscover-server-configuration");
return Promise.try(() => {
return Promise.all([
autodiscoverServerConfiguration.discover("pixie.town"), // wellKnown
autodiscoverServerConfiguration.discover("t2bot.io"), // srvLookup
autodiscoverServerConfiguration.discover("conduit.rs"), // wellKnownPort8448
autodiscoverServerConfiguration.discover("maunium.net"), // srvLookup, has delegatedHostname
]);
}).then((data) => {
console.log(data);
/*
[
{
method: 'wellKnown',
homeserver: 'https://pixie.town:443',
raw: { 'm.server': 'pixie.town:443' }
},
{
method: 'srvLookup',
homeserver: 'https://synapse.02.fsn1.ht.t2host.io:443',
raw: {
name: 'synapse.02.fsn1.ht.t2host.io',
port: 443,
priority: 10,
weight: 0
}
},
{
method: 'wellKnownPort8448',
homeserver: 'https://conduit.koesters.xyz:8448',
raw: { 'm.server': 'conduit.koesters.xyz' }
},
{
method: 'srvLookup',
homeserver: 'https://meow.host.mau.fi:443',
raw: { name: 'meow.host.mau.fi', port: 443, priority: 10, weight: 10 },
delegatedHostname: 'federation.mau.chat'
}
]
*/
}).catch(autodiscoverServerConfiguration.LookupFailed, (error) => {
console.error(error.message);
});
API
autodiscoverClientConfiguration.discover(hostname)
Attempt to determine the homeserver associated with the specified hostname
.
- hostname: The hostname to apply autodiscovery for. This may be either an explicitly-specified hostname (port optional) (not a URL!), IP literal, IP literal with port, or the server name extracted from a Matrix ID.
If no homeserver could be discovered, the returned Promise rejects with an autodiscoverServerConfiguration.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
(server + port from a.well-known/matrix/server
file),wellKnownPort8448
(using the server from the wellKnown response guessing port 8448), orsrvLookup
finding a server through the_matrix._tcp
SRV record(s). - homeserver: The base URL of the autodiscovered homeserver.
-
delegatedHostname: delegated_hostname of the autodiscovered homeserver, if available MUST be sent as the
Host:
header with every request -
raw: 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
/wellKnownPort8448
results, this data is the parsed response of.well-known/matrix/server
. - For
srvLookup
results, this data is the_matrix._tcp
SRV record with the lowest priority.
- For
autodiscoverServerConfiguration.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.1.4 (September 5th, 2021)
- Catch SSL altname invalid errors in WellKnown lookup
🏳️🌈 June 18th, 2021)
1.1.3 (- return cert fail error instead of throwing
🏳️🌈 June 18th, 2021)
1.1.2 (- remove debug console.log
🏳️🌈 June 18th, 2021)
1.1.1 (- server TLS certificate errors are now caught in server checks
🏳️🌈 June 17th, 2021)
1.1.0 (- add delegatedHostname for servers that have .well-known + SRV
🏳️🌈 June 17th, 2021)
1.0.3 (- add proper checkServerIdentity https agent for SRV records
🏳️🌈 June 17th, 2021)
1.0.2 (- Upgrade dependencies
🏳️🌈 June 17th, 2021)
1.0.1 (- Patch error handling for failed SRV lookups
- Patch url formatting with ports
1.0.0 (May 27th, 2021)
Forked from autodiscover-client-configuration, initial release.