handel-extension-api - npm Package Compare versions

Comparing version 0.26.9 to 0.26.10

dist/extension-api.d.ts

@@ -15,23 +15,99 @@ import { EC2 } from 'aws-sdk';
 export interface ServiceDeployer {
-    producedEventsSupportedServices: string[];
-    producedDeployOutputTypes: string[];
-    consumedDeployOutputTypes: string[];
+    providedEventType: ServiceEventType | null;
+    producedEventsSupportedTypes: ServiceEventType[];
+    producedDeployOutputTypes: DeployOutputType[];
+    consumedDeployOutputTypes: DeployOutputType[];
+    supportsTagging: boolean;
     /**
-     * If true, indicates that a deployer supports tagging its resources. This is used to enforce tagging rules.
+     * Checks the given service configuration in the user's Handel file for required parameters and correctness.
+     * This provides a fail-fast mechanism for configuration errors before deploy is attempted.
      *
-     * If not specified, 'true' is assumed, effectively making tagging enforcement opt-out.
+     * You should probably always implement this phase in every service deployer
+     */
+    check?(serviceContext: ServiceContext<ServiceConfig>, dependenciesServiceContexts: Array<ServiceContext<ServiceConfig>>): string[];
+    /**
+     * Create resources needed for deployment that are also needed for dependency wiring
+     * with other services.
      *
-     * If the deployer deploys anything to Cloudformation, it should declare that it supports tagging.
+     * Implement this phase if you'll be creating security groups for any of your resources
+     *
+     * Example AWS services that woulod need to implement this phase include Beanstalk and RDS
      */
-    supportsTagging: boolean;
-    check?(serviceContext: ServiceContext<ServiceConfig>, dependenciesServiceContexts: Array<ServiceContext<ServiceConfig>>): string[];
     preDeploy?(serviceContext: ServiceContext<ServiceConfig>): Promise<PreDeployContext>;
+    /**
+     * Bind two resources from the preDeploy phase together by performing some wiring action on them. An example
+     * is to add an ingress rule from one security group onto another.
+     *
+     * Bind is run from the perspective of the service being consumed, not the other way around. In other words, it
+     * is run on the dependency who is adding the ingress rule for the dependent service.
+     *
+     * Implement this phase if you'll be creating resources that need to add ingress rules for dependent services
+     * to talk to them
+     *
+     * Example AWS services that would need to implement this phase include RDS and EFS
+     */
     bind?(ownServiceContext: ServiceContext<ServiceConfig>, ownPreDeployContext: IPreDeployContext, dependentOfServiceContext: ServiceContext<ServiceConfig>, dependentOfPreDeployContext: IPreDeployContext): Promise<IBindContext>;
+    /**
+     * Deploy the resources contained in your service deployer.
+     *
+     * You are responsible for using the outputs in the dependenciesDeployContexts to wire up this service
+     * to those. For example, each one may return an IAM policiy that you should add to whatever role is
+     * created for your service.
+     *
+     * All this service's dependencies are guaranteed to be deployed before this phase gets called
+     */
     deploy?(ownServiceContext: ServiceContext<ServiceConfig>, ownPreDeployContext: IPreDeployContext, dependenciesDeployContexts: IDeployContext[]): Promise<IDeployContext>;
-    consumeEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, producerServiceContext: ServiceContext<ServiceConfig>, producerDeployContext: IDeployContext): Promise<IConsumeEventsContext>;
+    /**
+     * In this phase, this service should make any changes necessary to allow it to consume events from the given source
+     * For example, a Lambda consuming events from an SNS topic should add a Lambda Function Permission to itself to allow
+     * the SNS ARN to invoke it.
+     *
+     * This method will only be called if your service is listed as an event consumer in another service's configuration.
+     */
+    consumeEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, eventConsumerConfig: ServiceEventConsumer, producerServiceContext: ServiceContext<ServiceConfig>, producerDeployContext: IDeployContext): Promise<IConsumeEventsContext>;
+    /**
+     * In this phase, this service should make any changes necessary to allow it to produce events to the consumer service.
+     * For example, an S3 bucket producing events to a Lambda should add the event notifications to the S3 bucket for the
+     * Lambda.
+     *
+     * This method will only be called if your service has an event_consumers element in its configruation.
+     */
     produceEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, eventConsumerConfig: ServiceEventConsumer, consumerServiceContext: ServiceContext<ServiceConfig>, consumerDeployContext: IDeployContext): Promise<IProduceEventsContext>;
+    /**
+     * In this phase, the service should remove all resources created in the preDeploy phase.
+     *
+     * Implment this phase if you implemented the preDeploy phase!
+     */
     unPreDeploy?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnPreDeployContext>;
+    /**
+     * In this phase, the service should remove all bindings on preDeploy resources.
+     */
     unBind?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnBindContext>;
+    /**
+     * In this phase, the service should delete resources created during the deploy phase.
+     *
+     * Note that there are no 'unConsumeEvents' or 'unProduceEvents' phases. In most cases, deleting the
+     * service will automatically delete any event bindings the service itself has, but in some cases this phase will
+     * also need to manually remove event bindings. An example of this is CloudWatch Events, which requires that
+     * you remove all targets before you can delete the service.
+     */
     unDeploy?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnDeployContext>;
 }
+export declare enum DeployOutputType {
+    SecurityGroups = "SecurityGroups",
+    Policies = "Policies",
+    EnvironmentVariables = "EnvironmentVariables",
+    Scripts = "Scripts",
+    Credentials = "Credentials",
+}
+export declare enum ServiceEventType {
+    SNS = "SNS",
+    Lambda = "Lambda",
+    SQS = "SQS",
+    CloudWatchEvents = "CloudWatchEvents",
+    S3 = "S3",
+    DynamoDB = "DynamoDB",
+    IoT = "IoT",
+    AlexaSkillKit = "AlexaSkillKit",
+}
 /***********************************
@@ -89,3 +165,3 @@ * Types for the Account Config File
 export interface ServiceInfo {
-    producedEventsSupportedServices: string[];
+    producedEventsSupportedTypes: ServiceEventType[];
     producedDeployOutputTypes: string[];
@@ -120,3 +196,3 @@ consumedDeployOutputTypes: string[];
     serviceType: ServiceType;
-    eventOutputs: DeployContextEventOutputs;
+    eventOutputs: DeployContextEventOutputs | null;
     policies: any[];
@@ -133,3 +209,6 @@ environmentVariables: DeployContextEnvironmentVariables;
 export interface DeployContextEventOutputs {
-    [key: string]: any;
+    resourceName?: string;
+    resourceArn?: string;
+    resourcePrincipal: string;
+    serviceEventType: ServiceEventType;
 }
@@ -216,3 +295,3 @@ export declare function isDeployContextEventOutputs(obj: any | DeployContextEventOutputs): obj is DeployContextEventOutputs;
     serviceType: ServiceType;
-    eventOutputs: DeployContextEventOutputs;
+    eventOutputs: DeployContextEventOutputs | null;
     policies: any[];
@@ -219,0 +298,0 @@ environmentVariables: DeployContextEnvironmentVariables;

dist/extension-api.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+var DeployOutputType;
+(function (DeployOutputType) {
+    DeployOutputType["SecurityGroups"] = "SecurityGroups";
+    DeployOutputType["Policies"] = "Policies";
+    DeployOutputType["EnvironmentVariables"] = "EnvironmentVariables";
+    DeployOutputType["Scripts"] = "Scripts";
+    DeployOutputType["Credentials"] = "Credentials";
+})(DeployOutputType = exports.DeployOutputType || (exports.DeployOutputType = {}));
+var ServiceEventType;
+(function (ServiceEventType) {
+    ServiceEventType["SNS"] = "SNS";
+    ServiceEventType["Lambda"] = "Lambda";
+    ServiceEventType["SQS"] = "SQS";
+    ServiceEventType["CloudWatchEvents"] = "CloudWatchEvents";
+    ServiceEventType["S3"] = "S3";
+    ServiceEventType["DynamoDB"] = "DynamoDB";
+    ServiceEventType["IoT"] = "IoT";
+    ServiceEventType["AlexaSkillKit"] = "AlexaSkillKit";
+})(ServiceEventType = exports.ServiceEventType || (exports.ServiceEventType = {}));
 function isAccountConfig(obj) {
@@ -27,3 +46,3 @@ return !!obj
     return !!obj
-        && isArray(obj.producedEventsSupportedServices, isString)
+        && isArray(obj.producedEventsSupportedTypes, isString)
         && isArray(obj.producedDeployOutputTypes, isString)
@@ -66,3 +85,3 @@ && isArray(obj.consumedDeployOutputTypes, isString);
 function isDeployContextEventOutputs(obj) {
-    return isHash(obj);
+    return isHash(obj) || obj == null;
 }
@@ -106,3 +125,3 @@ exports.isDeployContextEventOutputs = isDeployContextEventOutputs;
         producedDeployOutputTypes: [],
-        producedEventsSupportedServices: []
+        producedEventsSupportedTypes: []
     }) {
@@ -176,3 +195,3 @@ this.appName = appName;
         this.serviceType = serviceContext.serviceType;
-        this.eventOutputs = {};
+        this.eventOutputs = null;
         this.policies = [];
@@ -179,0 +198,0 @@ this.environmentVariables = {};

extension-api.ts

@@ -22,3 +22,2 @@ /*
  ***********************************/
-
 export interface Extension {
@@ -36,33 +35,117 @@ loadHandelExtension(context: ExtensionContext): void | Promise<void>;
 export interface ServiceDeployer {
-    producedEventsSupportedServices: string[];
-    producedDeployOutputTypes: string[];
-    consumedDeployOutputTypes: string[];
+    // ------------------------------------------------
+    // Required metadata for the provisioner
+    // ------------------------------------------------
+    providedEventType: ServiceEventType | null; // The type of event type this deployer provides (if any)
+    producedEventsSupportedTypes: ServiceEventType[]; // The types of event types that this deployer can produce to (if)
+    producedDeployOutputTypes: DeployOutputType[]; // The types of deploy output types this deployer produces to other deployers
+    consumedDeployOutputTypes: DeployOutputType[]; // The types of deploy output types this deployer can consume from other deployers
+    supportsTagging: boolean; // If true, indicates that a deployer supports tagging its resources. This is used to enforce tagging rules.
+
+    // ------------------------------------------------
+    // Phase types that hte provisioner supports
+    // ------------------------------------------------
     /**
-     * If true, indicates that a deployer supports tagging its resources. This is used to enforce tagging rules.
+     * Checks the given service configuration in the user's Handel file for required parameters and correctness.
+     * This provides a fail-fast mechanism for configuration errors before deploy is attempted.
      *
-     * If not specified, 'true' is assumed, effectively making tagging enforcement opt-out.
-     *
-     * If the deployer deploys anything to Cloudformation, it should declare that it supports tagging.
+     * You should probably always implement this phase in every service deployer
      */
-    supportsTagging: boolean;
-
     check?(serviceContext: ServiceContext<ServiceConfig>, dependenciesServiceContexts: Array<ServiceContext<ServiceConfig>>): string[];
 
+    /**
+     * Create resources needed for deployment that are also needed for dependency wiring
+     * with other services.
+     *
+     * Implement this phase if you'll be creating security groups for any of your resources
+     *
+     * Example AWS services that woulod need to implement this phase include Beanstalk and RDS
+     */
     preDeploy?(serviceContext: ServiceContext<ServiceConfig>): Promise<PreDeployContext>;
 
+    /**
+     * Bind two resources from the preDeploy phase together by performing some wiring action on them. An example
+     * is to add an ingress rule from one security group onto another.
+     *
+     * Bind is run from the perspective of the service being consumed, not the other way around. In other words, it
+     * is run on the dependency who is adding the ingress rule for the dependent service.
+     *
+     * Implement this phase if you'll be creating resources that need to add ingress rules for dependent services
+     * to talk to them
+     *
+     * Example AWS services that would need to implement this phase include RDS and EFS
+     */
     bind?(ownServiceContext: ServiceContext<ServiceConfig>, ownPreDeployContext: IPreDeployContext, dependentOfServiceContext: ServiceContext<ServiceConfig>, dependentOfPreDeployContext: IPreDeployContext): Promise<IBindContext>;
 
+    /**
+     * Deploy the resources contained in your service deployer.
+     *
+     * You are responsible for using the outputs in the dependenciesDeployContexts to wire up this service
+     * to those. For example, each one may return an IAM policiy that you should add to whatever role is
+     * created for your service.
+     *
+     * All this service's dependencies are guaranteed to be deployed before this phase gets called
+     */
     deploy?(ownServiceContext: ServiceContext<ServiceConfig>, ownPreDeployContext: IPreDeployContext, dependenciesDeployContexts: IDeployContext[]): Promise<IDeployContext>;
 
-    consumeEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, producerServiceContext: ServiceContext<ServiceConfig>, producerDeployContext: IDeployContext): Promise<IConsumeEventsContext>;
+    /**
+     * In this phase, this service should make any changes necessary to allow it to consume events from the given source
+     * For example, a Lambda consuming events from an SNS topic should add a Lambda Function Permission to itself to allow
+     * the SNS ARN to invoke it.
+     *
+     * This method will only be called if your service is listed as an event consumer in another service's configuration.
+     */
+    consumeEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, eventConsumerConfig: ServiceEventConsumer, producerServiceContext: ServiceContext<ServiceConfig>, producerDeployContext: IDeployContext): Promise<IConsumeEventsContext>;
 
+    /**
+     * In this phase, this service should make any changes necessary to allow it to produce events to the consumer service.
+     * For example, an S3 bucket producing events to a Lambda should add the event notifications to the S3 bucket for the
+     * Lambda.
+     *
+     * This method will only be called if your service has an event_consumers element in its configruation.
+     */
     produceEvents?(ownServiceContext: ServiceContext<ServiceConfig>, ownDeployContext: IDeployContext, eventConsumerConfig: ServiceEventConsumer, consumerServiceContext: ServiceContext<ServiceConfig>, consumerDeployContext: IDeployContext): Promise<IProduceEventsContext>;
 
+    /**
+     * In this phase, the service should remove all resources created in the preDeploy phase.
+     *
+     * Implment this phase if you implemented the preDeploy phase!
+     */
     unPreDeploy?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnPreDeployContext>;
 
+    /**
+     * In this phase, the service should remove all bindings on preDeploy resources.
+     */
     unBind?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnBindContext>;
 
+    /**
+     * In this phase, the service should delete resources created during the deploy phase.
+     *
+     * Note that there are no 'unConsumeEvents' or 'unProduceEvents' phases. In most cases, deleting the
+     * service will automatically delete any event bindings the service itself has, but in some cases this phase will
+     * also need to manually remove event bindings. An example of this is CloudWatch Events, which requires that
+     * you remove all targets before you can delete the service.
+     */
     unDeploy?(ownServiceContext: ServiceContext<ServiceConfig>): Promise<IUnDeployContext>;
 }
 
+export enum DeployOutputType {
+    SecurityGroups = 'SecurityGroups',
+    Policies = 'Policies',
+    EnvironmentVariables = 'EnvironmentVariables',
+    Scripts = 'Scripts',
+    Credentials = 'Credentials'
+}
+
+export enum ServiceEventType {
+    SNS = 'SNS',
+    Lambda = 'Lambda',
+    SQS = 'SQS',
+    CloudWatchEvents = 'CloudWatchEvents',
+    S3 = 'S3',
+    DynamoDB = 'DynamoDB',
+    IoT = 'IoT',
+    AlexaSkillKit = 'AlexaSkillKit'
+}
+
 /***********************************
@@ -155,3 +238,3 @@ * Types for the Account Config File
 export interface ServiceInfo {
-    producedEventsSupportedServices: string[];
+    producedEventsSupportedTypes: ServiceEventType[];
     producedDeployOutputTypes: string[];
@@ -163,3 +246,3 @@ consumedDeployOutputTypes: string[];
     return !!obj
-        && isArray(obj.producedEventsSupportedServices, isString)
+        && isArray(obj.producedEventsSupportedTypes, isString)
         && isArray(obj.producedDeployOutputTypes, isString)
@@ -218,3 +301,3 @@ && isArray(obj.consumedDeployOutputTypes, isString)
     // Any outputs needed for producing/consuming events for this service
-    eventOutputs: DeployContextEventOutputs;
+    eventOutputs: DeployContextEventOutputs | null;
     // Policies the consuming service can use when creating service roles in order to talk to this service
@@ -249,7 +332,10 @@ policies: any[]; // There doesn't seem to be a great AWS-provided IAM type for Policy Documents
 export interface DeployContextEventOutputs {
-    [key: string]: any;
+    resourceName?: string;
+    resourceArn?: string;
+    resourcePrincipal: string;
+    serviceEventType: ServiceEventType;
 }
 
 export function isDeployContextEventOutputs(obj: any | DeployContextEventOutputs): obj is DeployContextEventOutputs {
-    return isHash(obj);
+    return isHash(obj) || obj == null;
 }
@@ -342,3 +428,3 @@
                     producedDeployOutputTypes: [],
-                    producedEventsSupportedServices: []
+                    producedEventsSupportedTypes: []
                 }) {
@@ -417,3 +503,3 @@ }
     // Any outputs needed for producing/consuming events for this service
-    public eventOutputs: DeployContextEventOutputs;
+    public eventOutputs: DeployContextEventOutputs | null;
     // Policies the consuming service can use when creating service roles in order to talk to this service
@@ -431,3 +517,3 @@ public policies: any[]; // There doesn't seem to be a great AWS-provided IAM type for Policy Documents
         this.serviceType = serviceContext.serviceType;
-        this.eventOutputs = {};
+        this.eventOutputs = null;
         this.policies = [];
@@ -434,0 +520,0 @@ this.environmentVariables = {};

package.json

 {
   "name": "handel-extension-api",
-  "version": "0.26.9",
+  "version": "0.26.10",
   "description": "API types and classes for Handel extensions",
@@ -5,0 +5,0 @@ "main": "dist/extension-api.js",

tsconfig.json

 {
     "extends": "../tsconfig",
     "compilerOptions": {
-        "outDir": "dist",
-        "declaration": true
+      "outDir": "dist"
     },
@@ -10,2 +9,2 @@ "include": [
     ]
-}
+}

No alert changes

Improved metrics

Total package byte prevSize

56874

increased by19.87%

Lines of code

1176

increased by18.67%

No dependency changes