@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), or srvLookup 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.

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

1.1.3 (🏳️‍🌈 June 18th, 2021)

• return cert fail error instead of throwing

1.1.2 (🏳️‍🌈 June 18th, 2021)

• remove debug console.log

1.1.1 (🏳️‍🌈 June 18th, 2021)

• server TLS certificate errors are now caught in server checks

1.1.0 (🏳️‍🌈 June 17th, 2021)

• add delegatedHostname for servers that have .well-known + SRV

1.0.3 (🏳️‍🌈 June 17th, 2021)

• add proper checkServerIdentity https agent for SRV records

1.0.2 (🏳️‍🌈 June 17th, 2021)

• Upgrade dependencies

1.0.1 (🏳️‍🌈 June 17th, 2021)

• 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.