at_lookup library

Upgrading from 3.x: see Upgrading to at_client 4.0.

Overview:

The AtLookup Library is the low-level direct implementation of the Atsign Protocol verbs. The AtLookup package is an interface to interact with an atServer: it sends verbs (scan, update, lookup, llookup, plookup and the rest) and reads their answers.

Get started:

Installation:

To add this package as the dependency, add it to your pubspec.yaml

dependencies:
  at_lookup: ^4.0.0

Add to your project

dart pub get

Import in your application code

import 'package:at_lookup/at_lookup_io.dart';

at_lookup.dart is the transport-neutral half: the verbs, AtLookUp, the outbound connection and the AtTransport interfaces. at_lookup_io.dart adds the native TLS transport and the atDirectory lookup, and re-exports everything above, so it is the one to import unless you are supplying your own transport and address finder.

Clone it from github

Feel free to fork a copy of the source from the GitHub Repo

Usage

To get the instance of at_lookup

import 'package:at_auth/at_auth.dart';
import 'package:at_auth/at_auth_io.dart';
import 'package:at_commons/at_commons.dart' show AtRootDomain;
import 'package:at_lookup/at_lookup_io.dart';

const root = AtRootDomain.atsignDomain;
final keysIo = FileAtKeysIo();   // the atSign's keyfile, from at_auth
final AtLookupMuxable atLookUp = AtLookUp.withSecureSocket(
  atSign: '@alice',
  rootDomain: root,
  transport: secureSocketTransport(SecureSocketConfig()),
  secondaryAddressFinder:
      CacheableSecondaryAddressFinder(root.rootDomain, root.rootPort),
  // How this connection authenticates, as one closure. at_lookup holds no key
  // material of its own; at_auth builds an authenticator from whatever
  // credential you have - a keystore, a bare private key, or a CRAM secret.
  // Pass null for a connection that never authenticates.
  authenticator: authenticatorFor(keysIo, '@alice'),
);

withSecureSocket returns an AtLookupMuxable, which is an AtLookUp that also carries the atServer's notification stream, so one connection and one parser handle both of the atServer's framings.

A factory, for a client that opens many connections

AtLookUpFactory is the function type an application hands at_client, so that every connection a client opens travels the way the application chose; secureSocketLookUps in package:at_lookup/at_lookup_io.dart is the default, TLS on TCP:

import 'package:at_lookup/at_lookup_io.dart';

// TLS with your own settings.
final lookUps = secureSocketLookUps(
    config: SecureSocketConfig()..pathToCerts = '/certs');

// Behind a proxy that routes on the atSign: `onConnect` runs once on each new
// connection, before anything else is sent on it.
final viaProxy = secureSocketLookUps(
    onConnect: (connection) => connection.sendSync('from:@alice\n'));

A factory of your own returns any AtLookupMuxable. Each call names what the connection is for: the atSign, the root domain, the authenticator (null for a connection that never authenticates) and an optional address finder; the client config goes to at_auth's authenticatorFor(clientConfig:). The factory captures how bytes travel. Please refer to examples for more details.

Open source usage and contributions

This is freely licensed open source code, so feel free to use it as is, suggest changes or enhancements or create your own version. See CONTRIBUTING.md for detailed guidance on how to setup tools, tests and make a pull request.