Skip to content

Commit

Permalink
PR comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshdover
joshdover committed Oct 15, 2019
1 parent b3eb270 commit 5f5d8ce
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 33 deletions.
15 changes: 13 additions & 2 deletions src/core/MIGRATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -610,10 +610,16 @@ At this point, your legacy server-side plugin logic is no longer coupled to lega

With both shims converted, you are now ready to complete your migration to the new platform.

Many plugins will copy and paste all of their plugin code into a new plugin directory and then delete their legacy shims.
Many plugins will copy and paste all of their plugin code into a new plugin directory in either `src/plugins` for OSS or `x-pack/plugins` for commerical code and then delete their legacy shims. It's at this point that you'll want to make sure to create your `kibana.json` file if it does not already exist.

With the previous steps resolved, this final step should be easy, but the exact process may vary plugin by plugin, so when you're at this point talk to the platform team to figure out the exact changes you need.

Other plugins may want to move subsystems over individually. For instance, you can move routes over to the New Platform in groups rather than all at once. Other examples that could be broken up:
- Configuration schema ([see example](./MIGRATION_EXAMPLES.md#declaring-config-schema))
- HTTP route registration
- Polling mechanisms (eg. job worker)

In general, we recommend moving all at once by ensuring you're not depending on any legacy code before you move over.

## Browser-side plan of action

Expand Down Expand Up @@ -857,6 +863,11 @@ Many plugins at this point will copy over their plugin definition class & the co

With the previous steps resolved, this final step should be easy, but the exact process may vary plugin by plugin, so when you're at this point talk to the platform team to figure out the exact changes you need.

Other plugins may want to move subsystems over individually. Examples of pieces that could be broken up:
- Registration logic (eg. viz types, embeddables, chrome nav controls)
- Application mounting
- Polling mechanisms (eg. job worker)

#### Bonus: Tips for complex migration scenarios

For a few plugins, some of these steps (such as angular removal) could be a months-long process. In those cases, it may be helpful from an organizational perspective to maintain a clear separation of code that is and isn't "ready" for the new platform.
Expand Down Expand Up @@ -1112,7 +1123,7 @@ _See also: [Server's CoreSetup API Docs](/docs/development/core/server/kibana-pl

#### UI Exports

The legacy platform uses a set of "uiExports" to inject modules from one plugin into other plugins. This mechansim is not necessary in the New Platform because all plugins are excuted on the page at once (though only one application) is rendered at a time.
The legacy platform uses a set of "uiExports" to inject modules from one plugin into other plugins. This mechansim is not necessary in the New Platform because all plugins are executed on the page at once (though only one application) is rendered at a time.

This table shows where these uiExports have moved to in the New Platform. In most cases, if a uiExport you need is not yet available in the New Platform, you may leave in your legacy plugin for the time being and continue to migrate the rest of your app to the New Platform.

Expand Down
74 changes: 43 additions & 31 deletions src/core/MIGRATION_EXAMPLES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,22 +26,21 @@ new kibana.Plugin({
});

// New Platform equivalent
import { schema } from '@kbn/config-schema';
import { schema, TypeOf } from '@kbn/config-schema';

// This object should be exported from your server-side plugin's index.ts file.
export const config = {
schema: schema.object({
enabled: schema.boolean({ defaultValue: true }),
defaultAppId: schema.string({ defaultValue: true }),
index: schema.string({ defaultValue: '.kibana' }),
disableWelcomeScreen: schema.boolean({ defaultValue: false }),
autocompleteTerminateAfter: schema.number({ min: 1, defaultValue: 100000 }),
autocompleteTerminateAfter: schema.duration({ min: 1, defaultValue: 100000 }),
})
};

// @kbn/config-schema is written in TypeScript, so you can use your schema
// definition to give you a type to use in your plugin code
type MyPluginConfig = typeof config.schema
// definition to create a type to use in your plugin code.
export type MyPluginConfig = TypeOf<typeof config.schema>;
```

### Using New Platform config from a Legacy plugin
Expand Down Expand Up @@ -72,8 +71,8 @@ the New Platform, we could create a NP plugin with the same name in

```ts
// src/plugins/timelion/server/index.ts
import { schema } from '@kbn/config-schema';
import { PluginInitializerContext } from '../../core/server';
import { schema, TypeOf } from '@kbn/config-schema';
import { PluginInitializerContext } from 'src/core/server';
import { TimelionPlugin } from './plugin';

export const config = {
Expand All @@ -84,7 +83,7 @@ export const config = {

export const plugin = (initContext: PluginInitializerContext) => new TimelionPlugin(initContext);

export type TimelionConfig = typeof config.schema;
export type TimelionConfig = TypeOf<typeof config.schema>;
export { TimelionSetup } from './plugin';
```

Expand All @@ -98,16 +97,21 @@ export class TimelionPlugin implements Plugin<TimelionSetup> {

public setup(core: CoreSetup) {
return {
config$: this.initContext.config.create<TimelionConfig>(),
__legacy: {
config$: this.initContext.config.create<TimelionConfig>(),
},
};
}

public setup() {}
public start() {}
public stop() {}
}

export interface TimelionSetup {
config$: Observable<TimelionConfig>;
/** @deprecated */
__legacy: {
config$: Observable<TimelionConfig>;
};
}
```

Expand All @@ -128,17 +132,22 @@ new kibana.Plugin({
## HTTP Routes

In the legacy platform, plugins have direct access to the Hapi `server` object
which gives full access to all of Hapi's API. In the New Platform, plugins
have access to the [HttpServiceSetup]() interface, which is exposed via the
[CoreSetup] object injected into the `setup` method of server-side plugins.
which gives full access to all of Hapi's API. In the New Platform, plugins have
access to the
[HttpServiceSetup](/docs/development/core/server/kibana-plugin-server.httpservicesetup.md)
interface, which is exposed via the
[CoreSetup](/docs/development/core/server/kibana-plugin-server.coresetup.md)
object injected into the `setup` method of server-side plugins.

This interface has a different API with slightly different behaviors.
- All input (body, query parameters, and URL parameters) must be validated using
the `@kbn/config-schema` package. If no validation schema is provided, these
values will be empty objects.
- All exceptions thrown by handlers result in 500 errors. If you need a specific
HTTP error code, catch any exceptions in your handler and construct the
appropriate response using the provided response factory.
appropriate response using the provided response factory. While you can
continue using the `boom` module internally in your plugin, the framework does
not have native support for converting Boom exceptions into HTTP responses.

### Route Registration

Expand All @@ -158,7 +167,7 @@ new kibana.Plugin({
}),
}
},
async handler(req, h) {
handler(req, h) {
return { message: `Received field1: ${req.payload.field1}` };
}
});
Expand All @@ -181,7 +190,7 @@ class Plugin {
}),
}
},
async (context, req, res) => {
(context, req, res) => {
return res.ok({
body: {
message: `Received field1: ${req.body.field1}`
Expand All @@ -198,8 +207,10 @@ class Plugin {
Services in the Legacy Platform were typically available via methods on either
`server.plugins.*`, `server.*`, or `req.*`. In the New Platform, all services
are available via the `context` argument to the route handler. The type of this
argument is the [RequestHandlerContext](). The APIs available here will include
all Core services and any services registered by plugins this plugin depends on.
argument is the
[RequestHandlerContext](/docs/development/core/server/kibana-plugin-server.requesthandlercontext.md).
The APIs available here will include all Core services and any services
registered by plugins this plugin depends on.

```ts
new kibana.Plugin({
Expand Down Expand Up @@ -241,15 +252,16 @@ In the Legacy Platform, the `ui/chrome` import contained APIs for a very wide
range of features. In the New Platform, some of these APIs have changed or moved
elsewhere.

| Legacy Platform | New Platform | Notes |
|-------------------------------------------------------|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `chrome.addBasePath` | `core.http.basePath.prepend` | |
| `chrome.breadcrumbs.set` | `core.chrome.setBreadcrumbs` | |
| `chrome.getUiSettingsClient` | `core.uiSettings` | |
| `chrome.helpExtension.set` | `core.chrome.setHelpExtension` | |
| `chrome.setVisible` | `core.chrome.setVisible` | |
| `chrome.getInjected` | -- | Not yet available, [comming soon]() |
| `chrome.setRootTemplate` / `chrome.setRootController` | -- | Use application mounting via `core.application.register` (not currently avaiable to legacy plugins). |

In most cases, the most convenient way to access these APIs will be via the [AppMountContext]()
object passed to your application when your app is mounted on the page. However, as of now, legacy applications cannot register apps with the New Platform. This [may change]().
| Legacy Platform | New Platform | Notes |
|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `chrome.addBasePath` | [`core.http.basePath.prepend`](/docs/development/core/public/kibana-plugin-public.httpservicebase.basepath.md) | |
| `chrome.breadcrumbs.set` | [`core.chrome.setBreadcrumbs`](/docs/development/core/public/kibana-plugin-public.chromestart.setbreadcrumbs.md) | |
| `chrome.getUiSettingsClient` | [`core.uiSettings`](/docs/development/core/public/kibana-plugin-public.uisettingsclient.md) | |
| `chrome.helpExtension.set` | [`core.chrome.setHelpExtension`](/docs/development/core/public/kibana-plugin-public.chromestart.sethelpextension.md) | |
| `chrome.setVisible` | [`core.chrome.setIsVisible`](/docs/development/core/public/kibana-plugin-public.chromestart.setisvisible.md) | |
| `chrome.getInjected` | [`core.injectedMetadata.getInjected`](/docs/development/core/public/kibana-plugin-public.coresetup.injectedmetadata.md) (temporary) | A temporary API is available to read injected vars provided by legacy plugins. This will be removed after [#41990](https://github.com/elastic/kibana/issues/41990) is completed. |
| `chrome.setRootTemplate` / `chrome.setRootController` | -- | Use application mounting via `core.application.register` (not currently avaiable to legacy plugins). |

In most cases, the most convenient way to access these APIs will be via the
[AppMountContext](/docs/development/core/public/kibana-plugin-public.appmountcontext.md)
object passed to your application when your app is mounted on the page.

0 comments on commit 5f5d8ce

Please sign in to comment.