From 009a23e4d6c03d2ebc6ff1062c368a55f18fe003 Mon Sep 17 00:00:00 2001 From: Mike Manfredi Date: Thu, 3 Oct 2024 16:17:01 +0000 Subject: [PATCH 1/3] some minor tweaks for missing details --- doc/psidk/src/development/services/rust-service/package.md | 6 +++--- doc/psidk/src/development/services/rust-service/testing.md | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/psidk/src/development/services/rust-service/package.md b/doc/psidk/src/development/services/rust-service/package.md index e4da867ed..05c9c1000 100644 --- a/doc/psidk/src/development/services/rust-service/package.md +++ b/doc/psidk/src/development/services/rust-service/package.md @@ -8,7 +8,7 @@ The available fields are: - `package-name`: Must be present on the top-level crate for the package. - `services`: A list of services to include in the psibase package. -- `server`: May be present on any crate that builds a service. The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package. +- `server`: May be present on any crate that builds a service. The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package. If HTTP requests are handled in the base service, it should reference the service. Can be omitted if service serves no HHTP requests. - `plugin`: May be present on any crate that builds a service. The value is a crate that should be built with `cargo component` and uploaded as `/plugin.wasm` - `flags`: [Flags](../../../specifications/data-formats/package.md#serviceservicejson) for the service. - `postinstall`: An array of actions to run when the package is installed. May be specified on the top-level crate or on any service. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified. @@ -24,7 +24,7 @@ version = "0.1.0" description = "An example package" [package.metadata.psibase] -# Builds example.psi +# (required) Builds example.psi package-name = "example" # Most services besides the core system services don't need extra flags. flags = [] @@ -32,7 +32,7 @@ flags = [] server = "example" # Plugin for the front end plugin = "example-plugin" -# Run the service's init action +# Run the service's init action; "0000" represents from the Fracpack perspective. postinstall = [{sender="tpack", service="tpack", method="init", rawData="0000"}] # Upload the UI data = [{src = "ui/", dst = "/"}] diff --git a/doc/psidk/src/development/services/rust-service/testing.md b/doc/psidk/src/development/services/rust-service/testing.md index f59b64666..a38eb9ab3 100644 --- a/doc/psidk/src/development/services/rust-service/testing.md +++ b/doc/psidk/src/development/services/rust-service/testing.md @@ -43,6 +43,7 @@ mod service { } } +// packages takes a comma-delimited list and references the package.metadata.psibase.package-name (case-sensitive) in Cargo.toml). The test chain will be initialized with default packages + services listed here. #[psibase::test_case(packages("example"))] fn test_arith(chain: psibase::Chain) -> Result<(), psibase::Error> { // Verify the actions work as expected. @@ -68,7 +69,8 @@ fn test_arith(chain: psibase::Chain) -> Result<(), psibase::Error> { } ``` -Add the following to `Cargo.toml`. This will allow `cargo psibase` to build a psibase package from the crate. +Add the following to `Cargo.toml`. This will allow `cargo psibase` to build a psibase package from the crate. See [Building Packages](package.md) for more details. + ```toml [package.metadata.psibase] package-name = "example" From e939cc5c9f730400ad3583c41e3e06766ef93649 Mon Sep 17 00:00:00 2001 From: Mike Manfredi Date: Thu, 3 Oct 2024 21:11:55 +0000 Subject: [PATCH 2/3] largely package-related changes --- .../services/rust-service/package.md | 54 +++++++++++++------ .../services/rust-service/testing.md | 4 +- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/doc/psidk/src/development/services/rust-service/package.md b/doc/psidk/src/development/services/rust-service/package.md index 05c9c1000..c487fd312 100644 --- a/doc/psidk/src/development/services/rust-service/package.md +++ b/doc/psidk/src/development/services/rust-service/package.md @@ -4,18 +4,29 @@ A [psibase package](../../../specifications/data-formats/package.md) may be comp `cargo psibase` reads the `[package.metadata.psibase]` section of `Cargo.toml`. At the minimum, `package-name` must be specified. -The available fields are: +## Available fields -- `package-name`: Must be present on the top-level crate for the package. +In the top-level crate: + +- `package-name`: Required. - `services`: A list of services to include in the psibase package. -- `server`: May be present on any crate that builds a service. The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package. If HTTP requests are handled in the base service, it should reference the service. Can be omitted if service serves no HHTP requests. -- `plugin`: May be present on any crate that builds a service. The value is a crate that should be built with `cargo component` and uploaded as `/plugin.wasm` + +In any crate that builds a service: + +- `server`: The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package. If HTTP requests are handled in the base service, it should reference the service. Can be omitted if service serves no HTTP requests. +- `plugin`: The value is a crate that should be built with `cargo component` and uploaded as `/plugin.wasm` - `flags`: [Flags](../../../specifications/data-formats/package.md#serviceservicejson) for the service. -- `postinstall`: An array of actions to run when the package is installed. May be specified on the top-level crate or on any service. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified. - `data`: An array of `{src, dst}` paths to upload to the service's subdomain. `src` is relative to the location of Cargo.toml. If `src` is a directory, its contents will be included recursively. -- `dependencies`: Additional packages, not build by cargo, that the package depends on. May be specified on the top-level crate or on any service. -Example: +We disagree on how to articulate this category, but one suggestion: +In top-level crate or any crate that builds a service: + +- `postinstall`: An array of actions to run when the package is installed. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified. +- `dependencies`: Additional packages, not build by cargo, that the package depends on. + +## Example + +./Cargo.toml ```toml [package] @@ -26,17 +37,30 @@ description = "An example package" [package.metadata.psibase] # (required) Builds example.psi package-name = "example" +# package includes `service1` service +services = ["service1"] + +[package.metadata.psibase.dependencies] +HttpServer = "0.13.0" +``` + +./service/Cargo.toml + +```toml +[package] +name = "service1" +version = "0.1.0" +description = "A service to be included in the package" + +[package.metadata.psibase] # Most services besides the core system services don't need extra flags. flags = [] # This service handles its own HTTP requests -server = "example" +server = "service1" # Plugin for the front end -plugin = "example-plugin" -# Run the service's init action; "0000" represents from the Fracpack perspective. -postinstall = [{sender="tpack", service="tpack", method="init", rawData="0000"}] +plugin = "service1-plugin" # Upload the UI -data = [{src = "ui/", dst = "/"}] - -[package.metadata.psibase.dependencies] -HttpServer = "0.13.0" +data = [{src = "../ui/dist", dst = "/"}] +# Run the service's init action; "0000" represents from the Fracpack perspective. +postinstall = [{sender="service1", service="service1", method="init", rawData="0000"}] ``` diff --git a/doc/psidk/src/development/services/rust-service/testing.md b/doc/psidk/src/development/services/rust-service/testing.md index a38eb9ab3..658766db8 100644 --- a/doc/psidk/src/development/services/rust-service/testing.md +++ b/doc/psidk/src/development/services/rust-service/testing.md @@ -43,7 +43,9 @@ mod service { } } -// packages takes a comma-delimited list and references the package.metadata.psibase.package-name (case-sensitive) in Cargo.toml). The test chain will be initialized with default packages + services listed here. +/* packages takes a comma-delimited list and references the + * package.metadata.psibase.package-name (case-sensitive) in Cargo.toml). + * The test chain will be initialized with default packages + services listed here. */ #[psibase::test_case(packages("example"))] fn test_arith(chain: psibase::Chain) -> Result<(), psibase::Error> { // Verify the actions work as expected. From 55a9da9eeaaea74ca1bafef556614b1de86dcf07 Mon Sep 17 00:00:00 2001 From: Mike Manfredi Date: Mon, 7 Oct 2024 15:03:15 +0000 Subject: [PATCH 3/3] updated missed comment --- doc/psidk/src/development/services/rust-service/package.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/psidk/src/development/services/rust-service/package.md b/doc/psidk/src/development/services/rust-service/package.md index c487fd312..95014f45c 100644 --- a/doc/psidk/src/development/services/rust-service/package.md +++ b/doc/psidk/src/development/services/rust-service/package.md @@ -18,7 +18,6 @@ In any crate that builds a service: - `flags`: [Flags](../../../specifications/data-formats/package.md#serviceservicejson) for the service. - `data`: An array of `{src, dst}` paths to upload to the service's subdomain. `src` is relative to the location of Cargo.toml. If `src` is a directory, its contents will be included recursively. -We disagree on how to articulate this category, but one suggestion: In top-level crate or any crate that builds a service: - `postinstall`: An array of actions to run when the package is installed. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified.