diff --git a/README.md b/README.md index 9f19593..b8968d1 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ simplify the creation of RESTful APIs including: ## Installation -To load the project in a Pharo image follow this [instructions](docs/how-to/how-to-load-in-pharo.md). +To load the project in a Pharo image follow these [instructions](docs/how-to/how-to-load-in-pharo.md). ## Contributing diff --git a/docs/MigrationGuide.md b/docs/MigrationGuide.md index df06a2a..0db5b22 100644 --- a/docs/MigrationGuide.md +++ b/docs/MigrationGuide.md @@ -11,7 +11,7 @@ - `Garbage Collector invokations` is now `Garbage Collector invocations` This name change can impact previously collected metrics or filters -- Dependencies udpated: +- Dependencies updated: - [`Launchpad`](https://github.com/ba-st/Launchpad) was updated to v4 - [`ZTimestamp`](https://github.com/svenvc/ztimestamp) is now a dependency - The application configuration plugin now needs that the `#provider` option @@ -26,7 +26,7 @@ expressions. To achieve this, manually load the package `Stargate-Deprecated-V6` Some changes can be automatically migrated from v2: -Manually load the package `Stargate-Deprecated-V3`. It includes deprecations, +Manually load the package `Stargate-Deprecated-V3`. It includes deprecation rules, some of them with automatic rewrite expressions. Other changes cannot be migrated in an automated fashion: @@ -42,14 +42,14 @@ Other changes cannot be migrated in an automated fashion: - `ResourceRESTfulControllerSpecification` is now deprecated so if you have subclasses you need to adapt the code to the new structure. - The mapping rules you have defined in the specification are now - deprecated. But you can reuse the mappings configuring the requestHandlerBuilder. + deprecated. But you can reuse the mappings configuring the `requestHandlerBuilder`. - Hypermedia controls support in the context must be always tied to some object, so the methods supporting hypermedia controls not attached to anything are deprecated. - `holdAsHypermediaControls:forSubresource:` was replaced by `holdAsHypermediaControls:for:` - `addPaginationControl:` was replaced by `addPaginationControls:` that provides a builder to ease the control creation. -- All the methods that were subclassResponsibility on +- All the methods that were `subclassResponsibility` on `ResourceRESTfulController` are no longer needed, now you must configure the builder to create a request handler with the desired behavior. @@ -74,7 +74,7 @@ Subclasses of `ResourceRESTfulController` must contemplate the following changes For the methods including the new argument, you can use your old implementation and ignore the context argument (Just change the method signature). For the -remaining subclassResponsibility implement it as: +remaining `subclassResponsibility` implement it as: ```smalltalk provideResourceCreationPolicy diff --git a/docs/explanation/Architecture.md b/docs/explanation/Architecture.md index 2950872..fe55219 100644 --- a/docs/explanation/Architecture.md +++ b/docs/explanation/Architecture.md @@ -75,7 +75,7 @@ the URI and the HTTP method involved in the request. - If a matching route is found: - A handler block is evaluated with the `HTTP request` and a new instance of `HttpRequestContext`. This context is carried over the whole response - computation so any component involved can share contextual information related + computation, so any component involved can share contextual information related to the current request. A handler block usually involves sending a message to a controller with the two mentioned arguments. - The receiving controller will collaborate with one of its request handlers diff --git a/docs/how-to/how-to-startup-API.md b/docs/how-to/how-to-startup-API.md index b2131c1..025b5b6 100644 --- a/docs/how-to/how-to-startup-API.md +++ b/docs/how-to/how-to-startup-API.md @@ -1,4 +1,4 @@ -# How to startup an API +# How to start up an API To start up an API you need to instantiate `HTTPBasedRESTfulAPI` providing the required configuration and the controllers to install. @@ -34,7 +34,7 @@ using port 9999. The configuration parameters are passed to `Teapot` so you can configure here any of the options accepted by `Teapot` or `Zinc` servers. The `operations` -key is mandatory and it's used for the plugin system of Stargate. See [the +key is mandatory, and it's used for the plugin system of Stargate. See [the operations and plugins documentation](Operations.md) to get a list of valid options. For deployment environments, the `jwt` authentication scheme is recommended. diff --git a/docs/reference/AuthenticationFilters.md b/docs/reference/AuthenticationFilters.md index 8f2253d..ba72958 100644 --- a/docs/reference/AuthenticationFilters.md +++ b/docs/reference/AuthenticationFilters.md @@ -10,7 +10,7 @@ There are two flavour of filters implemented: provided to the filter. If the validation is successful it will also make available through the `requestContext` the set of permissions encoded in the JWT. -- `ZnAuthenticationFilter` is an adapter over `ZnBasicAuthenticator` instances +- `ZnAuthenticationFilter` is an adapter over `ZnBasicAuthenticator` instances, so it can be used as authentication filter in the library. This adapter will send `isRequestAuthenticated:` to the authenticator to verify the authentication status. diff --git a/docs/reference/Baseline-groups.md b/docs/reference/Baseline-groups.md index 63c6838..ca696fa 100644 --- a/docs/reference/Baseline-groups.md +++ b/docs/reference/Baseline-groups.md @@ -12,7 +12,7 @@ loading targets: [Application Info plugin](ApplicationInfo.md) - `Application-Configuration` will load the packages needed to support the [Application Configuration plugin](ApplicationConfiguration.md) -- `Loggers` will load the packages needed to support the [Loggers plugin](Loggers.md) +- `Loggers` will load the packages needed to support the [Loggers plugin](Loggers.md) - `JSON-RPC` will load the packages needed to support JSON RPC APIs. - `Deployment` will load all the packages needed in a deployed application, which in this case correspond to `Core` + `HealthCheck` + `Metrics` + diff --git a/docs/reference/Controllers.md b/docs/reference/Controllers.md index 34af5d0..d308cd6 100644 --- a/docs/reference/Controllers.md +++ b/docs/reference/Controllers.md @@ -86,7 +86,7 @@ must be configured to produce a valid request handler: - For non-hypermedia driven controllers only implementing GET functionality over a resource, configure the builder using `handling:extractingIdentifierWith:`. - This method will receive an endpoint to handle and a block used to extract the + This method will receive an endpoint to handle, and a block used to extract the identifier of a resource instance from the request. For example: ```smalltalk @@ -97,7 +97,7 @@ must be configured to produce a valid request handler: ``` - For non-hypermedia driven controllers only implementing GET functionality over - a subresource, configure the builder using + a sub-resource, configure the builder using `handling:extractingIdentifierWith:locatingParentResourceWith:`. This method will receive additionally a resource locator to be used for locating the parent resource instance. For example: @@ -126,10 +126,10 @@ must be configured to produce a valid request handler: ``` - For hypermedia driven controllers or controllers implementing POST - functionality over a subresource, you will need to configure the builder using + functionality over a sub-resource, you will need to configure the builder using `handling:locatingSubresourcesWith:extractingIdentifierWith:locatingParentResourceWith:`. This method will require a configuration block used to produce the location of - the subresource. This block will receive the subresource instance and can + the sub-resource. This block will receive the sub-resource instance and can access the parent resource through the request context. For example: ```smalltalk @@ -202,7 +202,7 @@ the builder with one of the following methods: ## Collection Pagination -By default GET requests over collections will not be paginated. To get +By default, GET requests over collections will not be paginated. To get collections paginated, configure the builder by sending the message `paginateCollectionsWithDefaultLimit:` providing the default page limit. A request handler will parse `start` and `limit` as query parameters during a GET @@ -278,7 +278,7 @@ example classes and their respective tests: _shared_ caches _must revalidate_ the resources after _10 minutes_. - `SouthAmericanCurrenciesRESTfulController` offers `/currencies` as an _immutable_ resource, and `/currencies//banknotes` as an _immutable_ - resource fresh for _365.000.000 seconds_. + resource fresh for _365'000'000 seconds_. ## Language negotiation diff --git a/docs/reference/CrossOriginResourceSharing.md b/docs/reference/CrossOriginResourceSharing.md index be079c5..766080c 100644 --- a/docs/reference/CrossOriginResourceSharing.md +++ b/docs/reference/CrossOriginResourceSharing.md @@ -23,7 +23,7 @@ For a more detailed explanation about CORS, see [MDN web docs](https://developer CORS support is disabled by default. To enable it, send `allowCrossOriginSharingApplying:` message along with a configuration block to -the api. The simplest possible configuration is: +the API. The simplest possible configuration is: ```smalltalk api := HTTPBasedRESTfulAPI @@ -38,7 +38,7 @@ any origin. ### Configuring allowed origins -Allowed origins configuration is mandatory. There are two options available. +Allowed origin's configuration is mandatory. There are two options available. #### Allowing any origin @@ -63,7 +63,7 @@ port, or protocol. ### Requests with credentials -Optionally, to let the server to allow credentials, like cookies or basic HTTP +Optionally, to allow credentials in the server, like cookies or basic HTTP authentication, send `allowCredentials` into the configuration block. ```smalltalk diff --git a/docs/reference/Loggers.md b/docs/reference/Loggers.md index f3c7845..61c4d24 100644 --- a/docs/reference/Loggers.md +++ b/docs/reference/Loggers.md @@ -4,7 +4,7 @@ One of the operational plugins. It exposes information about the active loggers of the running application. This plugin is disabled by default and allows configuring the `Beacon` instance -to query. By default it will use the default `Beacon` instance. +to query. By default, it will use the default `Beacon` instance. This configuration is made via the `#operations` config. For example: diff --git a/docs/reference/Metrics.md b/docs/reference/Metrics.md index 9486e99..f66970f 100644 --- a/docs/reference/Metrics.md +++ b/docs/reference/Metrics.md @@ -31,8 +31,8 @@ Available metric providers: - `http` (optional group) gathers information over the incoming HTTP requests (request count, request duration, response size by HTTP method, response code, URL and URL template). The categories used for the breakdown can be filtered - by using the operations configuration, valid options are `#response_code`, - `#http_method`, `#url` and `#url_template`. By default all categories are + by using the operation's configuration, valid options are `#response_code`, + `#http_method`, `#url` and `#url_template`. By default, all categories are used for the breakdown. ## API @@ -42,7 +42,7 @@ Available metric providers: - Endpoint: `/metrics` - Allowed HTTP methods: `GET` - Supported media types: - - `text/plain`: In prometheus client data exposition format + - `text/plain`: In Prometheus client data exposition format - `text/vnd.stargate.prometheus.client-data-exposition;version=0.0.4`: The same as plain text but more explicit on the format - `application/vnd.stargate.operational-metrics+json` diff --git a/docs/reference/Operations.md b/docs/reference/Operations.md index a7a2bd0..c48f14a 100644 --- a/docs/reference/Operations.md +++ b/docs/reference/Operations.md @@ -5,7 +5,7 @@ supporting the operations team. An operational plugin has the following characteristics: -- Must expose operational information or allow to control some operation +- Must expose operational information or allow controlling some operation - It's optional. It can be enabled by default but should be possible to disable it - Must expose at least one endpoint to access its functionality under `/operations/{{plugin-endpoint}}` - Must be secured with a proper authorization filter. In specific cases a diff --git a/docs/reference/Skeleton.md b/docs/reference/Skeleton.md index eebba78..7f2e00c 100644 --- a/docs/reference/Skeleton.md +++ b/docs/reference/Skeleton.md @@ -51,7 +51,7 @@ String streamContents: [ :s | YourApplication printHelpOn: s]. ### Stack trace generation -By default stack traces are written in a `logs` directory relative to +By default, stack traces are written in a `logs` directory relative to the image's working directory in a filename whose name is `app-name-YYYY-MM-DD_HH-MM-SS.MS`, and in `Fuel` format. diff --git a/source/Stargate-API-Skeleton/StargateApplication.class.st b/source/Stargate-API-Skeleton/StargateApplication.class.st index 54015b5..77299a2 100644 --- a/source/Stargate-API-Skeleton/StargateApplication.class.st +++ b/source/Stargate-API-Skeleton/StargateApplication.class.st @@ -129,7 +129,7 @@ StargateApplication >> authAlgorithm [ ^ JWAHMACSHA256 parameterValue ] -{ #category : #'private - activation' } +{ #category : #'private - activation/deactivation' } StargateApplication >> basicStartWithin: context [ | api | @@ -142,7 +142,14 @@ StargateApplication >> basicStartWithin: context [ apiOptional := Optional containing: api ] -{ #category : #'private - activation' } +{ #category : #'private - activation/deactivation' } +StargateApplication >> basicStop [ + + apiOptional withContentDo: [ :api | api stop ]. + super basicStop +] + +{ #category : #'private - activation/deactivation' } StargateApplication >> configureGlobalErrorHandlerIn: api [ [ @@ -168,7 +175,7 @@ StargateApplication >> controllersToInstall [ ^ self subclassResponsibility ] -{ #category : #'private - activation' } +{ #category : #'private - activation/deactivation' } StargateApplication >> createAPI [ | api | @@ -180,13 +187,13 @@ StargateApplication >> createAPI [ ] { #category : #initialization } -StargateApplication >> initializeRunningIn: anApplicationMode configuredBy: aConfigurationProvider [ +StargateApplication >> initialize [ - super initializeRunningIn: anApplicationMode configuredBy: aConfigurationProvider. + super initialize. apiOptional := Optional unused ] -{ #category : #'private - activation' } +{ #category : #'private - activation/deactivation' } StargateApplication >> installAndStart: api [ LaunchpadLogRecord @@ -194,7 +201,7 @@ StargateApplication >> installAndStart: api [ emitInfo: 'Starting API' during: [ api start ] ] -{ #category : #'private - activation' } +{ #category : #'private - activation/deactivation' } StargateApplication >> logAPIVersion [ BasicApplicationInformationProvider new applicationNamed: self class commandName @@ -250,9 +257,3 @@ StargateApplication >> stargateConfiguration [ ^ self configuration stargate ] - -{ #category : #'private - activation' } -StargateApplication >> stop [ - - apiOptional withContentDo: [ :api | api stop ] -]