atlassian_connect_shelf 0.11.2

Atlassian Connect Shelf based server. Includes middleware for authentication. Leverages all the other acdart components like jwt, host services and config

Atlassian Connect Shelf Server

Introduction

Provides a server based on the Shelf library.

It includes the following Shelf Middleware components:

• productHostAuthenticator. A Shelf Middleware component for authenticating requests from product hosts
• sessionTokenAuthenticator. A Shelf Middleware component for authenticating requests from the addon client code using the Atlassian Connect session token mechanism

In addition it includes:

• AcDartRouter. An extension of a Shelf Route router adding:

  • helpers for easily defining core routes such as for handling installation requests and serving atlassian-connect.json
  • Additional Shelf Bind custom objects to support injection of the following into handlers
    • AcSessionContext containing the session information relating to the current request
    • AcHostService for all host related services for the Atlassian product host that is associated with the current request.
    • AcHostHttpClient to communicate with the Atlassian product host that is associated with the current request.
    • AcHostRegistration the registration details for the Atlassian product host that is associated with the current request.
    • AcDartRequestContext a wrapper object that contains access to the other context objects aiding discoverability

• AcDartApp. Provides a convenient entry point into the app

The Shelf Server uses all the other Atlassian Connect Dart libraries. It's the easiest way to get started and we believe provides a good solution. However, if you prefer another web framework then you can still use all the other Atlassian Connect Dart libraries, greatly reducing the effort to get up and running.

Using

Basic Usage

Note there is an example project that is in the example folder of the library that illustrates basic usage.

Create your Configuration

See the documentation for the Atlassian Connect Configuration library for details.

Define your Routes

Create your app and set up the routes by using the acdart function as the entry point. Call start when ready to bring up the server.

void main() {
  final app = acdart(config);
  
  // add standard handlers for installation and descriptor
  app.router..addInstallationRoute()
            ..addDescriptorTemplateRoute();
  
  // define a child route for all routes that will be authenticated via addon session token
  app.router.child('/service',
      middleware: app.addonSessionAuthenticator)
      ..get('/issue/{issueKey}', _fetchJiraIssue)
      ..put('/issue/{issueKey}', _updateJiraIssue);
      
  // define a child route for all routes that will be authenticated via Atlassian Host token
  app.router.child('/ui',
      middleware: app.atlassianHostAuthenticator)
      ..get('/exampleUI.html',
          app.moustacheFile('ui/exampleUI.html', includeExtraParams: true));
  
  // start your engines
  app.start();
}

Request handlers (thanks to Shelf Bind) are just ordinary Dart functions and have access to the additional objects injected via AcDartApp.

In this case the issueKey was defined on the route (/issue/{issueKey}) so can simply be accessed as a function parameter and AcHostHttpClient is one of the objects AcDart can inject for you.

As the route is a child of /service it is authenticated via the Addon Session token so the AcHostHttpClient object will be initialised for communication with the correct host.

Future<Map> _fetchJiraIssue(String issueKey, AcHostHttpClient httpClient) {
  _log.fine('fetching jira issue $issueKey');

  final jiraResponse =
      httpClient.get('rest/api/2/issue/$issueKey', signRequest: true)
        .then((req) => req.close());

  return jiraResponse
      .then(HttpBodyHandler.processResponse)
      .then((body) => body.body);
}