Architecture

How does a request from your application reach the document engine, and what does DS Server keep on disk? Knowing its parts, the addresses they answer on and the way OAuth sits in front of them helps you plan an installation, open the right ports and configure a client. The sections below follow a request from the client to the worker processes.

Architecture at a Glance

DS Server is one ASP.NET Core application, TXTextControl.DocumentServices, that serves every part of the product under one base address:

Your applications                                           DS Server (TXTextControl.DocumentServices)

Browser: Document Editor  --WebSocket /documenteditor/WS->  Document Editor
Browser: Document Viewer  --HTTP /documentviewer--------->  Document Viewer
Any backend or script     --HTTP /documentprocessing----->  DocumentProcessing Web API
                          --HTTP /oauth/token------------>  OAuth server (security profiles)
Admin in a browser        --HTTP /----------------------->  Admin portal
Admin scripts             --HTTP /admin, /license-------->  Admin Web API
                                                            |
                                                            v
                                                        Worker processes with the TX Text Control engine
                                                        Admin.db (LiteDB), logs, Plugins

• One server, one address. The base address is the service URL that every client is configured with, for example https://yourdomain.com/DocumentServices behind IIS or http://localhost:5000 when DS Server runs on its own.
• OAuth in front of the services. Once an admin enables OAuth, the Document Editor, the Document Viewer and the DocumentProcessing Web API accept a request only with an access token issued for a security profile. On a new installation, OAuth is disabled and these services accept requests without a token.
• Separate worker processes do the document work beside the web application.

The Server Application

The files of DS Server are a published ASP.NET Core application: TXTextControl.DocumentServices.dll, its dependencies, configuration files and a wwwroot folder with the admin portal and the Document Editor script. You host it in one of these ways:

• Kestrel. You start it with dotnet TXTextControl.DocumentServices.dll, and the ASP.NET Core web server Kestrel serves it. This works on Linux and Windows, and the Dockerfile of the Linux Docker guide starts DS Server the same way. See Manual Installation and Installing with Official Image from Docker Hub.
• IIS. The included web.config hosts the application in-process with the ASP.NET Core Module V2. It also sets the IIS request filtering limit for query strings to 8,192 bytes.
• Windows service. Since version 3.0, DS Server can be registered as a Windows service.

Ports

When Kestrel hosts DS Server, hostsettings.json sets the addresses it listens on:

{
    "urls": "http://*:5000;https://*:5001"
}

Port 5000 serves HTTP and port 5001 serves HTTPS. The HTTPS address needs a certificate: without one, DS Server stops at startup with the message "Unable to configure HTTPS endpoint". The official Docker image listens on port 5000 only, and the Dockerfiles of the Docker guides remove the HTTPS address. For production, you configure HTTPS with a certificate, as described in HTTPS. Behind IIS, the ports are those of the IIS site.

Configuration and Data on Disk

DS Server writes the database into its own folder and the logs into the working directory it is started from, so the account it runs under needs write access to both. Configuration covers the settings in detail.

Worker Processes

Next to the web application, the archive contains three worker process assemblies, named after the services they belong to:

The worker processes contain the TX Text Control engine that processes the documents; the changelog of DS Server refers to them as the DocumentProcessing worker process and the document editor worker process. They ship in the same folder as the server application. Their runtime requirements are listed in Core and Classic.

OAuth and Security Profiles

DS Server contains its own OAuth 2.0 authorization server. An admin creates a security profile for each application in the admin portal or through the admin Web API. Each profile has a client ID and a client secret, and optionally a list of authorized redirect URIs and an expiry date.

A client exchanges these credentials for an access token and sends the token with every request:

• Authorization code flow. The client requests a code from GET /oauth/authorize with its client ID and a redirect URI. DS Server sends the code only to a redirect URI registered in the profile, and the client exchanges it for an access token and a refresh token at POST /oauth/token. The ASP.NET Core client packages use this flow when you set a redirect URI, and handle the callback in your application, for example at https://yourdomain.com/textcontrol/documenteditor/auth/callback.
• Client credentials flow. A backend sends its client ID and client secret in a Basic authorization header to POST /oauth/token and receives an access token directly. This flow is disabled by default and is enabled per security profile. Use it only where the secret stays on a server, never in code that runs in a browser.
• Using the token. A request passes the access token in an Authorization: Bearer header or in the access_token query parameter. A token is valid for 3,600 seconds.

The admin portal and the admin Web API are protected separately, with the admin user name and password in a Basic authorization header. See Creating Security Profiles and OAuth Grant Types.

How Clients Connect

Every client needs the service URL and the credentials of a security profile. What it sends depends on the service:

The Document Editor keeps a WebSocket connection to DS Server. Its script builds the address from the service URL, with wss: for an https service URL and ws: for http, and the path /documenteditor/WS. This is why IIS needs its WebSocket Protocol feature, as listed in Requirements. The Document Viewer and the DocumentProcessing Web API use plain HTTP requests.

Client-Side Libraries describes the packages, and Getting Started builds a first application with each of them.

Plugins

A plugin is a .NET assembly that implements the IPlugin interface of the TXTextControl.DocumentServices.Plugin.Abstractions package. DS Server loads every plugin from its own subfolder of Plugins/ at startup, so you restart DS Server after adding or updating one. A plugin can register ASP.NET Core controllers and middleware, which then answer under DS Server's address. Since version 5.0, plugins can use the services IDocumentProcessingService and IDocumentEditorSessionService to reach the document processing features and the open Document Editor sessions. See Plugins.

More Than One Server

A single installation serves all your applications. To spread the load across several servers:

• Security profiles must be known on every server. You create them on each server, clone them with the admin Web API, or register other DS Server instances as authentication servers: a server forwards an authorization it cannot confirm itself to them. Authentication servers are available since version 3.1.
• Sticky sessions. A Document Editor session lives on the server that opened it, so the load balancer must send every connection of a client to the same server, for example with source IP affinity.
• Licenses. Every server installation needs its own license. See Licensing Overview.

Multiple Servers with Load Balancing describes the setup.

Next Steps

• Core and Classic: the two builds, their platforms, formats and runtime requirements.
• Installation Guide: install DS Server with Docker, by hand or behind IIS.
• Creating Security Profiles: the credentials your applications use.
• Web API: every endpoint with its parameters and responses.