Welcome to xio’s documentation!

Contents:

XIO Quickstart

Maven Artifacts

Simple HTTP Application

Application

The Application object holds all of the global state and configuration data across multiple server objects. It should be configured and instantiated by an ApplicationBootstrap instance.

1
2
3
4
Application application = new ApplicationBootstrap("example.application")
  .addServer("echo", (serverBootstrap) -> serverBootstrap.addToPipeline(new EchoPipeline()))
  .addServer("http", (serverBootstrap) -> serverBootstrap.addToPipeline(new HttpPipeline()))
  .build();

Each application will be created with a configuration server which may be used to update dynamic configuration values while the application is running.

Server

The XioServer object holds the state and configuration data for a single server instance. It should be configured and instantiated by a XioServerBootstrap object.

1
2
3
XioServer server = XioServerBootstrap.fromConfig("example.application")
  .addToPipeline(new XioHttp1_1Pipeline())
  .build();

Each server will be created with a XioServerInstrumentation object which can be used to interrogate the server about the bound InetSocketAddress and the application protocol that the server is configured for.

The workhorse of the Server is the pipeline, in the previous example we create a simple http 1.1 pipeline that will response with 404 to any request.

Client

The Client object holds the state and configuration data for a single abstract client. Depending on the concrete implementation the client could be connected to multiple servers in a cluster, or just a single server. It should be configured and instantiated by a XioClientBootstrap object.

1
2
3
4
XioClient client = new XioClientBootstrap(new NioEventLoopGroup())
  .setAddress(new InetSocketAddress("10.10.10.10", 443))
  .handler(new SimpleInboundChannelHandler())
  .build();

The handler defines how the client will interact with the remote server. By default clients will use HTTP as their application protocol.

Core

SSL

application

bootstrap

client

config

core

filter

handler

marshall

mux

pipeline

proxy

server

service

storage

Configuration

Static Configuration

XIO strives to use static configuration values over hard coded constants whenever possible. Static configuration in XIO is done with Typesafe Config. XIO provides sensible defaults static configuration values.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
xio {

  // default values for application limits
  applicationLimits {
    // maximum number of connections across all servers in the application
    maxConnections = 15000
  }

  // default values for server limits
  serverLimits {
    // maximum number of connections for a single server instance
    maxConnections = 500
    // maximum frame size per connection
    maxFrameSize = 9600
    // triggered when no read was performed for the specified period of time. Specify 0 to disable.
    maxReadIdleTime = 60seconds
    // triggered when no write was performed for the specified period of time. Specify 0 to disable.
    maxWriteIdleTime = 60seconds
    // triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.
    maxAllIdleTime = 60seconds
  }

  // default values for application settings
  applicationSettings {
    // location of the zookeeper cluster DEPRECATED
    zookeeperCluster = ""
    zookeeper {
      // location of the zookeeper cluster
      cluster = "localhost:2181"
      client {
        retry {
          // zookeeper client retry policy
          policy = RetryOneTime
          // policy must match one of the following sections:
          BoundedExponentialBackoffRetry {
            // see: https://curator.apache.org/apidocs/org/apache/curator/retry/BoundedExponentialBackoffRetry.html
            baseSleepDuration = 2seconds
            maxSleepDuration = 10seconds
            maxRetries = 10
          }
          ExponentialBackoffRetry {
            // https://curator.apache.org/apidocs/org/apache/curator/retry/ExponentialBackoffRetry.html
            baseSleepDuration = 2seconds
            maxRetries = 10
          }
          RetryForever {
            // https://curator.apache.org/apidocs/org/apache/curator/retry/RetryForever.html
            sleepDuration = 2seconds
          }
          RetryNTimes {
            // https://curator.apache.org/apidocs/org/apache/curator/retry/RetryNTimes.html
            n = 10
            sleepDuration = 2seconds
          }
          RetryOneTime {
            // https://curator.apache.org/apidocs/org/apache/curator/retry/RetryOneTime.html
            sleepDuration = 2seconds
          }
          RetryUntilElapsed {
            // https://curator.apache.org/apidocs/org/apache/curator/retry/RetryUntilElapsed.html
            maxElapsedDuration = 10seconds
            sleepDuration = 2seconds
          }
        }
      }
    }
    // number of boss threads to create
    bossThreads = 5
    // boss thread name format
    bossNameFormat = "xio-application-boss-%d"
    // number of worker threads to create
    workerThreads = 10
    // worker thread name format
    workerNameFormat = "xio-application-worker-%d"
    // settings for dynamic configuration manager
    configurationManager {
      ipFilter {
        // path to monitor for ip filter rules
        path = "/xio/ipFilterRules"
      }
      http1Filter {
        // path to monitor for http filter rules
        path = "/xio/http1FilterRules"
      }
    }
    // settings for configuration update server
    configurationUpdateServer {
      // update server is disabled by default
      enabled = false
      // update server is bound to port 9999 on loopback by default
      bindIp = 127.0.0.1
      bindPort = 9999
      // update server will coalesce changes and persist them every 5 seconds by default
      writeInterval = 5seconds
    }
    // settings for muxing client
    requestMuxer {
      messagesPerBatch = 100
      drainMessageQInterval = 1millisecond
      multiplierIncrementInterval = 500milliseconds
      multiplierDecrementInterval = 750milliseconds
      rebuildConnectionLoopInterval = 250milliseconds
    }
  }

  serverSettings {
    // servers bind to port 80 on loopback by default
    bindIp = 127.0.0.1
    bindPort = 80
    // DEPRECATED
    bossThreads = 5
    // DEPRECATED
    workerThreads = 10
    // xio message logger is enabled by default
    messageLoggerEnabled = true
    // load self signed cert by default
    tls { include classpath("tls.conf") }
  }

  applicationTemplate {
    // application name defaults to blank
    name = ""
    limits = ${xio.applicationLimits}
    settings = ${xio.applicationSettings}
  }

  serverTemplate {
    // server name defaults to blank
    name = ""
    limits = ${xio.serverLimits}
    settings = ${xio.serverSettings}
  }

  // example of how to build an xio application from templates
  exampleApplication = ${xio.applicationTemplate} {
    name = "example application"
    servers {
      exampleServer = ${xio.serverTemplate} {name = "example server"}
    }
  }

  exampleServer = ${xio.serverTemplate} {name = "example"}

  servers = [
  #  ${exampleServer}
  ]

  testApplication = ${xio.applicationTemplate} {
    name = "test application"
    servers {
      testServer = ${xio.serverTemplate} {
        name = "test server"
        settings {
          bindPort = 0
        }
      }
    }
  }
}

Dynamic Configuration

Configuration Server

Configuration Client

XIO Examples

example-trailhead

XIO Logging

log4j-formatter

Hacking xio

Maven

mvn

IntelliJ

Makefile

emacs

Building the docs

Indices and tables