feat(socket-engine): introduce package (#999)

Author: Fabian Wiles

WORKSPACE

@@ -1,9 +1,9 @@
 workspace(name = "nguniversal")
 http_archive(
     name = "build_bazel_rules_nodejs",
-    url = "https://github.com/bazelbuild/rules_nodejs/archive/0.9.1.zip",
-    strip_prefix = "rules_nodejs-0.9.1",
-    sha256 = "6139762b62b37c1fd171d7f22aa39566cb7dc2916f0f801d505a9aaf118c117f",
+    # TODO: upgrade once https://github.com/bazelbuild/rules_nodejs/issues/218#issuecomment-395826361 is released
+    url = "https://github.com/bazelbuild/rules_nodejs/archive/0.8.0.zip",
+    strip_prefix = "rules_nodejs-0.8.0",
 )
 
 http_archive(

modules/socket-engine/BUILD.bazel

@@ -0,0 +1,46 @@
+load("//tools:defaults.bzl", "ts_library", "ng_module", "ng_package")
+
+package(default_visibility = ["//visibility:public"])
+
+load("@build_bazel_rules_nodejs//:defs.bzl", "jasmine_node_test")
+
+ng_module(
+    name = "socket-engine",
+    srcs = glob([
+        "*.ts",
+        "src/**/*.ts",
+    ]),
+    module_name = "@nguniversal/socket-engine",
+    deps = [
+        "//modules/common",
+    ],
+)
+
+ng_package(
+    name = "npm_package",
+    srcs = [
+        ":package.json",
+    ],
+    entry_point = "modules/socket-engine/index.js",
+    readme_md = ":README.md",
+    deps = [
+        ":socket-engine",
+        "//modules/common",
+    ],
+)
+
+ts_library(
+    name = "unit_test_lib",
+    testonly = True,
+    srcs = glob([
+        "spec/**/*.spec.ts",
+    ]),
+    deps = [
+        ":socket-engine",
+    ],
+)
+
+jasmine_node_test(
+    name = "unit_test",
+    srcs = [":unit_test_lib"],
+)

modules/socket-engine/README.md

@@ -0,0 +1,44 @@
+# Angular Universal Socket Engine
+
+Framework and Platform agnostic Angular Universal rendering.
+
+## Usage Server
+
+`npm install @nguniversal/socket-engine @nguniversal/common --save`
+
+```js
+const socketEngine = require('@nguniversal/socket-engine');
+
+// * NOTE :: leave this as require() since this file is built Dynamically from webpack
+const {AppServerModuleNgFactory, LAZY_MODULE_MAP} = require('./dist/server/main');
+
+socketEngine.startSocketEngine(AppServerModuleNgFactory);
+```
+This will the socket engine which internally hosts a TCP Socket server.  
+The default port is `9090` and host of `localhost`
+You may want to leave this as a plain `.js` file since it is so simple and to make deploying it easier, but it can be easily transpiled from Typescript.  
+
+## Usage Client
+
+Your client can be whatever language, framework or platform you like.  
+As long as it can connect to a TCP Socket (which all frameworks can) then you're good to go.
+
+This example will use JS for simplicity
+```typescript
+import * as net from 'net';
+
+const client = net.createConnection(9090, 'localhost', () => {
+  console.log('connected to SSR server');
+});
+
+client.on('data', data => {
+  const res = JSON.parse(data.toString()) as SocketEngineResponse;
+  expect(res.id).toEqual(1);
+  expect(res.html).toEqual(template);
+  server.close();
+  done();
+});
+
+const renderOptions = {id: 1, url: '/path', document: '<app-root></app-root>'} as SocketEngineRenderOptions;
+client.write(JSON.stringify(renderOptions));
+```

modules/socket-engine/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export * from './public_api';

modules/socket-engine/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@nguniversal/socket-engine",
+  "version": "0.0.0-PLACEHOLDER",
+  "description": "Socket Engine for running Server Angular Apps",
+  "license": "MIT",
+  "keywords": [
+    "socket",
+    "ssr",
+    "universal"
+  ],
+  "peerDependencies": {
+    "@nguniversal/common": "0.0.0-PLACEHOLDER",
+    "@angular/core": "NG_VERSION"
+  },
+  "ng-update": {
+    "packageGroup": "NG_UPDATE_PACKAGE_GROUP"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/angular/universal"
+  },
+  "bugs": {
+    "url": "https://github.com/angular/universal/issues"
+  },
+  "homepage": "https://github.com/angular/universal"
+}

modules/socket-engine/public_api.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export { startSocketEngine, SocketEngineResponse, SocketEngineRenderOptions } from './src/main';

modules/socket-engine/spec/index.spec.ts

@@ -0,0 +1,91 @@
+
+import { ServerModule } from '@angular/platform-server';
+import { NgModule, Component } from '@angular/core';
+import 'zone.js';
+
+import { BrowserModule } from '@angular/platform-browser';
+import { startSocketEngine, SocketEngineResponse,
+  SocketEngineRenderOptions } from '@nguniversal/socket-engine';
+import * as net from 'net';
+
+export function makeTestingModule(template: string, component?: any): any {
+  @Component({
+    selector: 'root',
+    template: template
+  })
+  class MockComponent {}
+  @NgModule({
+    imports: [ServerModule, BrowserModule.withServerTransition({appId: 'mock'})],
+    declarations: [component || MockComponent],
+    bootstrap: [component || MockComponent]
+  })
+  class MockServerModule {}
+  return MockServerModule;
+}
+
+async function sendAndRecieve(renderOptions: SocketEngineRenderOptions, template = '') {
+  return new Promise<SocketEngineResponse>(async(resolve, _reject) => {
+
+    const appModule = makeTestingModule(template);
+    const server = await startSocketEngine(appModule);
+
+    const client = net.createConnection(9090, 'localhost', () => {
+      client.write(JSON.stringify(renderOptions));
+    });
+
+    client.on('data', data => {
+      const res = JSON.parse(data.toString()) as SocketEngineResponse;
+      server.close();
+      resolve(res);
+    });
+  });
+}
+
+describe('test runner', () => {
+  it('should render a basic template', async (done) => {
+    const template = `${new Date()}`;
+    const renderOptions = {id: 1, url: '/path',
+        document: '<root></root>'} as SocketEngineRenderOptions;
+    const result = await sendAndRecieve(renderOptions, template);
+    expect(result.html).toContain(template);
+    done();
+  });
+  it('should return the same id', async(done) => {
+    const id = Math.random();
+    const renderOptions = {id , url: '/path',
+        document: '<root></root>'} as SocketEngineRenderOptions;
+    const result = await sendAndRecieve(renderOptions);
+    expect(result.id).toEqual(id);
+    done();
+  });
+  it('should return an error if it cant render', async(done) => {
+    @Component({
+      selector: 'root',
+      template: ''
+    })
+    class MockComponent {constructor(_illMakeItThrow: '') {}}
+    const appModule = makeTestingModule('', MockComponent);
+    const server = await startSocketEngine(appModule);
+
+    const client = net.createConnection(9090, 'localhost', () => {
+      const renderOptions = {id: 1, url: '/path',
+      document: '<root></root>'} as SocketEngineRenderOptions;
+      client.write(JSON.stringify(renderOptions));
+    });
+
+    client.on('data', data => {
+      const res = JSON.parse(data.toString()) as SocketEngineResponse;
+      server.close();
+      expect(res.error).not.toBeNull();
+      done();
+    });
+  });
+  it('should return an error if it cant render', async(done) => {
+    const template = `${new Date()}`;
+    const renderOptions = {id: 1, url: '/path',
+        document: '<root></root>'} as SocketEngineRenderOptions;
+    const result = await sendAndRecieve(renderOptions, template);
+    expect(result.error).toBeUndefined();
+    done();
+  });
+});

modules/socket-engine/src/main.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { ɵCommonEngine as CommonEngine,
+  ɵRenderOptions as RenderOptions } from '@nguniversal/common/engine';
+import { NgModuleFactory, Type } from '@angular/core';
+import * as net from 'net';
+
+export interface SocketEngineServer {
+  close: () => void;
+}
+
+export interface SocketEngineRenderOptions extends RenderOptions {
+  id: number;
+}
+
+export interface SocketEngineResponse {
+  id: number;
+  html: string|null;
+  error?: Error;
+}
+
+export function startSocketEngine(
+  moduleOrFactory: Type<{}> | NgModuleFactory<{}>,
+  host = 'localhost',
+  port = 9090
+): Promise<SocketEngineServer> {
+  return new Promise((resolve, _reject) => {
+    const engine = new CommonEngine(moduleOrFactory);
+
+    const server = net.createServer(socket => {
+      socket.on('data', async buff => {
+        const message = buff.toString();
+        const renderOptions = JSON.parse(message) as SocketEngineRenderOptions;
+        try {
+          const html = await engine.render(renderOptions);
+          socket.write(JSON.stringify({html, id: renderOptions.id} as SocketEngineResponse));
+        } catch (error) {
+          // send the error down to the client then rethrow it
+          socket.write(JSON.stringify({html: null,
+            id: renderOptions.id, error} as SocketEngineResponse));
+          throw error;
+        }
+      });
+    });
+
+    server.listen(port, host);
+    resolve({close: () => server.close()});
+  });
+}
+