diff --git a/functions_framework/CHANGELOG.md b/functions_framework/CHANGELOG.md index 291f0fb6..f3172f4f 100644 --- a/functions_framework/CHANGELOG.md +++ b/functions_framework/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 0.4.1-dev +## 0.4.1 - Improve package documentation. diff --git a/functions_framework/README.md b/functions_framework/README.md index 0a910ed7..26c35aa5 100644 --- a/functions_framework/README.md +++ b/functions_framework/README.md @@ -86,7 +86,7 @@ properly format your code. ## Licensing -Apache 2.0; see [`LICENSE`](LICENSE) for details. +Apache 2.0; see [`LICENSE`][license] for details. [ff_dart]: https://github.com/GoogleCloudPlatform/functions-framework-dart @@ -123,3 +123,4 @@ https://github.com/GoogleCloudPlatform/functions-framework-dart/actions?query=wo [cloud run quickstart]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/docs/quickstarts/03-quickstart-cloudrun.md [quickstarts]: https://github.com/GoogleCloudPlatform/functions-framework-dart/tree/main/docs/quickstarts [contributing]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/CONTRIBUTING.md +[license]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/functions_framework/LICENSE diff --git a/functions_framework/example/readme.md b/functions_framework/example/readme.md new file mode 100644 index 00000000..0fecabbc --- /dev/null +++ b/functions_framework/example/readme.md @@ -0,0 +1,4 @@ +# Functions Framework Examples + +For usage examples, see +https://github.com/GoogleCloudPlatform/functions-framework-dart/tree/main/examples diff --git a/functions_framework/lib/functions_framework.dart b/functions_framework/lib/functions_framework.dart index 9067a19b..93a1591b 100644 --- a/functions_framework/lib/functions_framework.dart +++ b/functions_framework/lib/functions_framework.dart @@ -12,6 +12,18 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// Provides the features needed to *define* Cloud Functions. +/// +/// ```dart +/// // lib/functions.dart +/// import 'package:functions_framework/functions_framework.dart'; +/// import 'package:shelf/shelf.dart'; +/// +/// @CloudFunction() +/// Response function(Request request) => Response.ok('Hello, World!'); +/// ``` +library functions_framework; + export 'src/bad_request_exception.dart' show BadRequestException; export 'src/cloud_event.dart' show CloudEvent; export 'src/cloud_function.dart' show CloudFunction; diff --git a/functions_framework/lib/serve.dart b/functions_framework/lib/serve.dart index 3b869660..1e675432 100644 --- a/functions_framework/lib/serve.dart +++ b/functions_framework/lib/serve.dart @@ -12,6 +12,16 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// Provides the features needed to *execute* Cloud Functions. +/// +/// Typically, this library is imported in `bin/server.dart` or similar. +/// +/// While it's possible to use this library from hand-written code, you should +/// use +/// [package:functions_framework_builder](https://pub.dev/packages/functions_framework_builder) +/// to generate server code instead. +library serve; + import 'dart:async'; import 'dart:io'; diff --git a/functions_framework/lib/src/cloud_event.dart b/functions_framework/lib/src/cloud_event.dart index 707f89ae..48a3f68f 100644 --- a/functions_framework/lib/src/cloud_event.dart +++ b/functions_framework/lib/src/cloud_event.dart @@ -16,6 +16,10 @@ import 'package:json_annotation/json_annotation.dart'; part 'cloud_event.g.dart'; +/// Represents [CloudEvents](https://cloudevents.io/) data. +/// +/// Use this as the parameter in a function you wish to use as a handler for +/// CloudEvents. @JsonSerializable(includeIfNull: false, checked: true) class CloudEvent { @JsonKey(required: true) diff --git a/functions_framework/lib/src/log_severity.dart b/functions_framework/lib/src/log_severity.dart index 4af98c12..d85e67c6 100644 --- a/functions_framework/lib/src/log_severity.dart +++ b/functions_framework/lib/src/log_severity.dart @@ -12,6 +12,17 @@ // See the License for the specific language governing permissions and // limitations under the License. +import 'request_context.dart'; +import 'typedefs.dart'; + +/// Allows logging at a specified severity. +/// +/// Can be used as the second parameter in functions shaped like +/// [HandlerWithLogger]. Also exposed by [RequestContext]. +/// +/// Compatible with the +/// [log severities](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity) +/// support by Google Cloud. abstract class RequestLogger { const RequestLogger(); diff --git a/functions_framework/lib/src/request_context.dart b/functions_framework/lib/src/request_context.dart index 660eb92a..8081b6bc 100644 --- a/functions_framework/lib/src/request_context.dart +++ b/functions_framework/lib/src/request_context.dart @@ -15,9 +15,15 @@ import 'package:meta/meta.dart'; import 'package:shelf/shelf.dart'; +import 'cloud_event.dart'; import 'log_severity.dart'; import 'logging.dart'; +/// Provides access to a [RequestLogger], the source [Request] and response +/// headers for a typed function handler. +/// +/// Can be used as an optional second parameter in a function definition that +/// accepts a [CloudEvent] or a custom type. class RequestContext { final RequestLogger logger; diff --git a/functions_framework/lib/src/typedefs.dart b/functions_framework/lib/src/typedefs.dart index 69ee6f4a..779159cf 100644 --- a/functions_framework/lib/src/typedefs.dart +++ b/functions_framework/lib/src/typedefs.dart @@ -20,22 +20,43 @@ import 'cloud_event.dart'; import 'log_severity.dart'; import 'request_context.dart'; +/// The shape of a handler for [CloudEvent] types. typedef CloudEventHandler = FutureOr Function(CloudEvent request); +/// The shape of a handler for [CloudEvent] types while also providing a +/// [RequestContext]. typedef CloudEventWithContextHandler = FutureOr Function( CloudEvent request, RequestContext context, ); +/// The shape of a handler that supports a custom [RequestType] and +/// [ResponseType]. +/// +/// The [RequestType] must be either a type compatible with a JSON literal or +/// have a `fromJson` constructor with a single, positional parameter that is +/// compatible with a JSON literal. +/// +/// The [ResponseType] must be either a type compatible with a JSON literal or +/// have a `toJson()` function with a returns type compatible with a JSON +/// literal. typedef JsonHandler = FutureOr Function(RequestType request); +/// The shape of a handler that supports a custom [RequestType] and +/// [ResponseType] and while also providing a [RequestContext]. +/// +/// See [JsonHandler] for the type requirements for [RequestType] and +/// [ResponseType]. typedef JsonWithContextHandler = FutureOr Function( RequestType request, RequestContext context, ); +/// The shape of a basic handler that follows the +/// [package:shelf](https://pub.dev/packages/shelf) [Handler] pattern while also +/// providing a [RequestLogger]. typedef HandlerWithLogger = FutureOr Function( Request request, RequestLogger logger, diff --git a/functions_framework/pubspec.yaml b/functions_framework/pubspec.yaml index 1b2f7b85..6d2dcc1c 100644 --- a/functions_framework/pubspec.yaml +++ b/functions_framework/pubspec.yaml @@ -1,5 +1,5 @@ name: functions_framework -version: 0.4.1-dev +version: 0.4.1 description: >- FaaS (Function as a service) framework for writing portable Dart functions repository: https://github.com/GoogleCloudPlatform/functions-framework-dart