diff --git a/content/en/documentation/for-adopters/data-plane/_index.md b/content/en/documentation/for-adopters/data-plane/_index.md index 2f31db1..ffa3484 100644 --- a/content/en/documentation/for-adopters/data-plane/_index.md +++ b/content/en/documentation/for-adopters/data-plane/_index.md @@ -15,7 +15,7 @@ the data consumer. This section provides an overview of how data planes work and Although a data plane can be collocated in the same process as a control plane, this is not a recommended setup. Typically, a data plane component is deployed as a separate set of instances to an independent environment such as a Kubernetes cluster. -This allows the data plane to be operated and scaled independently from the control plane. At runtime, a data plane must +This allows the data plane to be operated and scaled independently of the control plane. At runtime, a data plane must register with a control plane, which in turn directs the data plane using the *Data Plane Signaling API*. EDC does not ship with an out-of-the-box data plane. Rather, it provides the *Data Plane Framework (DPF)*, a platform for building custom data planes. You can choose to start with the DPF or build your own data plane using your programming language diff --git a/content/en/documentation/for-adopters/extensions/_index.md b/content/en/documentation/for-adopters/extensions/_index.md index d52ff6d..1057af7 100644 --- a/content/en/documentation/for-adopters/extensions/_index.md +++ b/content/en/documentation/for-adopters/extensions/_index.md @@ -76,7 +76,7 @@ The SPI pattern is further used to define *extension points*. An extension point ### Providing and Injecting Services -The EDC module system assembles extensions into a runtime by wiring services to `ServiceExtensions` that require them and initialing the latter. An extension can *provide* services that are used by other extensions. This is done by annotating a factory method with the `org.eclipse.edc.runtime.metamodel.annotation.Provider` annotation: +The EDC module system assembles extensions into a runtime by wiring services to `ServiceExtensions` that require them and instantiating the latter. An extension can *provide* services that are used by other extensions. This is done by annotating a factory method with the `org.eclipse.edc.runtime.metamodel.annotation.Provider` annotation: ```java public class SampleExtension implements ServiceExtension { @@ -334,7 +334,7 @@ The EDC eventing system is a powerful way to add capabilities to a runtime. All - Contract negotiations - Transfer processes -To receive an event, register and `EventSubscriber` with the `org.eclipse.edc.spi.event.EventRouter`. Events can be received either synchronously or asynchronously. Synchronous listeners are useful when executed transactionally in combination with the event operation. For example, a listener may wish to record audit information when an `AssetUpdated` event is emitted. The transaction and asset update should be rolled back if the record operation fails. Asynchronous listeners are invoked in the context of a different thread. They are useful when a listener takes a long time to complete and is fire-and-forget. +To receive an event, register an `EventSubscriber` with the `org.eclipse.edc.spi.event.EventRouter`. Events can be received either synchronously or asynchronously. Synchronous listeners are useful when executed transactionally in combination with the event operation. For example, a listener may wish to record audit information when an `AssetUpdated` event is emitted. The transaction and asset update should be rolled back if the record operation fails. Asynchronous listeners are invoked in the context of a different thread. They are useful when a listener takes a long time to complete and is fire-and-forget. ### Monitor diff --git a/content/en/documentation/for-adopters/identity-hub/_index.md b/content/en/documentation/for-adopters/identity-hub/_index.md index a118871..f0f3acc 100644 --- a/content/en/documentation/for-adopters/identity-hub/_index.md +++ b/content/en/documentation/for-adopters/identity-hub/_index.md @@ -109,7 +109,7 @@ Many organizations prefer to manage identity resources centrally, as strict secu ### Per Dataspace Component -Some organizations may prefer to manage their identity resources at the dataspace level. For example, a multinational may participate in multiple regional dataspaces. Each dataspace may be geographically restricted, requiring all data and resources to be regionally fenced. In this case, an Identity Hub can deployed for each regional dataspace, allowing for separate management and isolation. +Some organizations may prefer to manage their identity resources at the dataspace level. For example, a multinational may participate in multiple regional dataspaces. Each dataspace may be geographically restricted, requiring all data and resources to be regionally fenced. In this case, an Identity Hub can be deployed for each regional dataspace, allowing for separate management and isolation. ### Embedded @@ -166,7 +166,7 @@ When a key pair is created, it is not yet used to sign resources. When a key pai For security reasons, key pair resources should be periodically rotated and replaced by new ones. Identity Hub supports a staged rotation process to avoid service disruptions and ensure that existing signed resources can still be validated for a specified period. -For example, let's assume private key A is used to sign Credential CA and public key A' is used to verify CA. If the key pair A-A' is immediately revoked, CA can no longer be validated, which may cause a service disruption. Key rotation can be used to avoid this. When the key pair A-A' is rotated, a new key pair, B-B', is created and used to sign resources. The private key A is immediately destroyed. A', however, will remain as a verification method in the DID document associated with the participant context. CA validation will continue to work. When CA and all other resources signed by A expire, A' can safely be removed from the DID document. +For example, let's assume private key A is used to sign Credential CA and public key A' is used to verify CA. If the key pair A-A' is immediately revoked, CA can no longer be validated, which may cause a service disruption. Key rotation can be used to avoid this. When the key pair A-A' is rotated, a new key pair, B-B', is created and used to sign resources. The private key A is immediately destroyed. A', however, will remain as a verification method in the DID document associated with the participant context. CA validation will continue to work. When CA and all other resources signed by A expires, A' can safely be removed from the DID document. > It's important to perform key rotation periodically to enhance overall system security. This implies that signed resources should have a validity period less than the rotation period of the key used to sign them and should also be reissued on a frequent basis. diff --git a/content/en/documentation/for-adopters/issuer-service/_index.md b/content/en/documentation/for-adopters/issuer-service/_index.md index 0b407a3..52db198 100644 --- a/content/en/documentation/for-adopters/issuer-service/_index.md +++ b/content/en/documentation/for-adopters/issuer-service/_index.md @@ -104,7 +104,7 @@ This enables the IssuerService to link additional data to the holder, which may `credentialSubject` of the Verifiable Credential. Furthermore, the IssuerService can enforce that only known holders are allowed to request credentials. -There may, however, be use cases where is is _not_ necessary, or even desirable, to pre-register holders in the +There may, however, be use cases where it is _not_ necessary, or even desirable, to pre-register holders in the IssuerService. In such cases, the IssuerService can be configured to allow anonymous credential requests, i.e., holders can simply make a CredentialRequest without being pre-registered in the IssuerService. @@ -244,7 +244,7 @@ Please check out the full [OpenAPI specification of the IssuerService Administra ## Deployment Options -As all other EDC components, the IssuerService is comprised of a set of Java modules that can be packaged and deployed +As all other EDC components, the IssuerService is composed of a set of Java modules that can be packaged and deployed in various ways. The clear recommendation is to deploy the IssuerService as a standalone runtime with its own HSM (vault) and its own diff --git a/content/en/documentation/for-adopters/tuning/_index.md b/content/en/documentation/for-adopters/tuning/_index.md index 2fa31ed..a47bf6e 100644 --- a/content/en/documentation/for-adopters/tuning/_index.md +++ b/content/en/documentation/for-adopters/tuning/_index.md @@ -13,7 +13,7 @@ weight: 80 Out of the box the EDC provides a set of default configurations that aim to find a good balance for performances. The extensibility nature of the EDC permits the user to configure it deeply. -We will explain how these settings can be fine tuned +We will explain how these settings can be fine-tuned. ## State Machines At the core of the EDC there is the [`State Machine`](../../for-contributors/runtime/programming-primitives.md#1-state-machines) @@ -30,7 +30,7 @@ The most important settings for configuring a state machine are: pessimistically against mutual access, so for the time of the processing no other connector instances can read the same entities. - `send.retry.limit` - - how many time a failing process execution can be tried before failure. + - how many times a failing process execution can be tried before failure. - `send.retry.base-delay.ms` - how many milliseconds have to pass before the first retry after a failure. Next retries are calculated with an exponential function (e.g. if the first delay is 10ms) diff --git a/content/en/documentation/for-contributors/_index.md b/content/en/documentation/for-contributors/_index.md index 34c1baf..eb11bed 100644 --- a/content/en/documentation/for-contributors/_index.md +++ b/content/en/documentation/for-contributors/_index.md @@ -124,7 +124,7 @@ Detailed documentation about entities can be found [here](./control-plane/entiti ### 2.2 Policy Monitor -The policy monitor is a component that watches over on-going transfers and ensures that the policies associated with the +The policy monitor is a component that watches over ongoing transfers and ensures that the policies associated with the transfer are still valid. Detailed documentation about the policy monitor can be found [here](./control-plane/policy-monitor.md) diff --git a/content/en/documentation/for-contributors/best-practices.md b/content/en/documentation/for-contributors/best-practices.md index 67cd931..479848b 100644 --- a/content/en/documentation/for-contributors/best-practices.md +++ b/content/en/documentation/for-contributors/best-practices.md @@ -35,7 +35,7 @@ This document is not an exhaustive list of prescribed steps, that will shield ad danger, but rather should serve as starting point for engineers to build upon. Finally, it should go without saying that the software of the EDC project is distributed "as is" and committers of EDC -take no responsibility or liability, direct or indirect, for any harm or damage caused by the us`e of it. This document +take no responsibility or liability, direct or indirect, for any harm or damage caused by the use of it. This document does not change that. ## 2. Security recommendations @@ -65,12 +65,12 @@ purpose of performing authentication, authorization, rate limiting, IP blacklist There is a plethora of ready-made components available, both commercial and open-source, therefor the EDC project _will not provide that functionality._ Feature requests and issues to that effect will be ignored. -In the particular case of the DSP API, the same principle holds, although with the exception of authentication and +In the particular case of the DSP API, the same principle holds, although except for authentication and authorization. That is handled by the [DSP protocol itself](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol). We have a rudimentary token-based API security module available, which can be used to secure the connection API gateway -<-> connector if so desired. It should be noted that it is _not designed to act as a ingress point!_ +<-> connector if so desired. It should be noted that it is _not designed to act as an ingress point!_ > TL;DR: don't expose any APIs if you can help it, but if you must, use available tools to harden the ingress @@ -79,7 +79,7 @@ We have a rudimentary token-based API security module available, which can be us Typically, JVMs ship with trust stores that contain a number of widely accepted CAs. Any attempts to package additional CAs/certificates with runtime base images are _discouraged_, as that would be problematic because: -- scalability: in a heterogenous networks one cannot assume such a custom CA to be accepted by the counterparty +- scalability: in a heterogeneous networks one cannot assume such a custom CA to be accepted by the counterparty - maintainability: TLS certificates expire, so there is a chance that mandatory software rollouts become necessary because of expired certificates lest the network breaks down completely. - security: there have been a number of issues with CAs diff --git a/content/en/documentation/for-contributors/control-plane/entities/_index.md b/content/en/documentation/for-contributors/control-plane/entities/_index.md index 0d9b702..059775a 100644 --- a/content/en/documentation/for-contributors/control-plane/entities/_index.md +++ b/content/en/documentation/for-contributors/control-plane/entities/_index.md @@ -64,7 +64,7 @@ A very simplistic `Asset` could look like this: ``` The `Asset` also contains a `DataAddress` object, which can be understood as a "pointer into the physical world". It -contains information about where the asset is physically located. This could be a HTTP URL, or a complex object. In the +contains information about where the asset is physically located. This could be an HTTP URL, or a complex object. In the S3 example, that `DataAddress` might contain the bucket name, region and potentially other information. Notice that the _schema_ of the `DataAddress` will depend on where the data is physically located, for instance a `HttpDataAddress` has different properties from an S3 `DataAddress`. More precisely, Assets and DataAddresses are _schemaless_, so there is no @@ -76,7 +76,7 @@ recommend using the JDK `UUID` implementation. Second, _never_ store access credentials such as passwords, tokens, keys etc. in the `dataAddress` or even the `privateProperties` object. While the latter does not get serialized over DSP, both properties are persisted in the -database. Always use a HSM to store the credential, and hold a reference to the secret in the DataAddress. Checkout +database. Always use an HSM to store the credential, and hold a reference to the secret in the DataAddress. Checkout [the best practices](../contributor-handbook.md#4-development-best-practices) for details. By design, Assets are extensible, so users can store any metadata they want in it. For example, the `properties` object @@ -220,7 +220,7 @@ an invalid operator should raise an exception. ### 2.1 Policy vs PolicyDefinition -In EDC we have two general use cases under which we handle and persist policies: +In EDC, we have two general use cases under which we handle and persist policies: 1. for use in contract definitions 2. during contract negotiations @@ -231,7 +231,7 @@ definitions. > Side note: the ODRL context available at `http://www.w3.org/ns/odrl.jsonld` simply defines `uid` as an alias to the > `@id` property. This means, whether we use `uid` or `@id` doesn't matter, both expand to the same property `@id`. -However in the second case we are dealing with DCAT objects, that have no concept of Offers, Policies or Assets. Rather, +However, in the second case we are dealing with DCAT objects, that have no concept of Offers, Policies or Assets. Rather, their vocabulary includes Datasets, Dataservices etc. So when deserializing those DCAT objects there is no way to reconstruct `Policy#uid`, because the JSON-LD structure does not contain it. @@ -405,12 +405,12 @@ Let's revisit our headquarter policy from earlier and change it a little: } ``` -This means two things. One, our policy has changed its semantics: now we require the headquarter to be in the EU, or to +This means two things. One, our policy has changed its semantics: now we require the headquarters to be in the EU, or to have more than 5000 employees. #### 2.5.3 Policy Validation and Evaluation Plan -By default ODRL policies are validated only in their structure (e.g. fields missing). In the latest +By default, ODRL policies are validated only in their structure (e.g. fields missing). In the latest version of EDC an additional layer of validation has been introduced which leverages the `PolicyEngine` configuration in the `runtime` as described [above](#22-policy-scopes-and-bindings) in order to have a more domain-specific validation. @@ -457,7 +457,7 @@ Let's take this policy as example: } ``` -> Since we are using `@vocab`, the `leftOperand` `headquarter.location` vaule defaults to the `edc` namespace, i.e. will get transformed during JSON-LD expansion to `"https://w3id.org/edc/v0.0.1/ns/headquarter.location"` +> Since we are using `@vocab`, the `leftOperand` `headquarter.location` value defaults to the `edc` namespace, i.e. will get transformed during JSON-LD expansion to `"https://w3id.org/edc/v0.0.1/ns/headquarter.location"` and let's assume that we didn't bind the policy to any function or scope, the output of the validation might look like this: @@ -483,14 +483,14 @@ Since the `leftOperand` is not bound to a scope and there is no function associa The kind validation can be called using the `/v3.1alpha/policydefinitions/{id}/validate` or can be enabled by default on policy definition creation. -> The settings is `edc.policy.validation.enabled` and is set to `false` by default +> The setting is `edc.policy.validation.enabled` and is set to `false` by default #### 2.5.3.2 Policy Evaluation Plan Even if the validation phase of a policy is successful, it might happen that evaluation of a `Policy` does not behave as expected if the `PolicyEngine` was not configured properly. -One suche example would be if a function is bound only to a `leftOperand` in the `catalog` scope, but the desired behavior is to execute the policy function also in the `contract.negotiation` and in the `transfer.process` scopes. +One such example would be if a function is bound only to a `leftOperand` in the `catalog` scope, but the desired behavior is to execute the policy function also in the `contract.negotiation` and in the `transfer.process` scopes. In those scenarios, the new API called the "evaluation plan API" has been introduced to get an overview of all the steps that the `PolicyEngine` will take while evaluating a `Policy` within a scope without actually running the evaluation. By using the same policy example, we could run an evaluation plan for the `contract.negotiation` scope: @@ -563,7 +563,7 @@ expressing which policies are in effect for an asset. So when an asset (or sever a contract definition is used to express under what conditions they are offered. Those conditions are comprised of a _contract policy_ and an _access policy_. The _access policy_ determines, whether a participant will even get the offer, and the contract policy determines whether they can negotiate a contract for it. Those policies are referenced by ID, -but foreign-key constrainta are not enforced. This means that contract definitions can be created _ahead of time_. +but foreign-key constraints are not enforced. This means that contract definitions can be created _ahead of time_. It is important to note that contract definitions are _implementation details_ (i.e. _internal objects_), which means they **never** leave the realm of the provider, and they are **never** sent to the consumer via DSP. @@ -910,7 +910,7 @@ where: how and where the data transfer should happen. - [`callbackAddresses`](#73-transfer-process-callbacks) custom hooks in order bo be notified about state transition of the transfer process. -- `privateProperties`: custom properties not shared with the counter party. +- `privateProperties`: custom properties not shared with the counter-party. ### 7.1 Transfer and data flows types @@ -948,9 +948,9 @@ Then it's up to the consumer to use this information for pulling the data. can either decide to receive the `DataAddress` using the eventing system [callbacks](#73-transfer-process-callbacks) using the `transfer.process.started` type, or use the [EDRs](#8-endpoint-data-references) extensions for automatically store it on consumer control plane side. -10. With the informations in the `DataAddress` such as the `endpointUrl` and the `Authorization` data can be fetched. +10. With the information in the `DataAddress` such as the `endpointUrl` and the `Authorization` data can be fetched. 11. The Provider Data plane validates and authenticates the incoming request and retrieves the source `DataAddress`. -12. The he provider data plane proxies the validated request to the configured backend in the source `DataAddress`. +12. The provider data plane proxies the validated request to the configured backend in the source `DataAddress`. #### 7.1.2 Provider Push @@ -971,24 +971,24 @@ A push transfer is when the Provider data plane initiates sending data to the de through [data plane signaling](../contributor-handbook.md#210-data-plane-signaling) protocol. 6. The Provider Data Plane validates the incoming request 7. If request is valid, the Provider Data Plane returns acknowledgement -8. The `DataPlaneManager` of the the Provider Data Plane processes the request: it creates a `DataSource`/`DataSink`pair +8. The `DataPlaneManager` of the Provider Data Plane processes the request: it creates a `DataSource`/`DataSink`pair based on the source/destination data addresses 9. The Provider Data Plane fetches data from the actual data source (see `DataSource`) 10. The Provider Data Plane pushes data to the consumer services (see `DataSink`) #### 7.1.2 Finite and Non-Finite Data -The charaterization of the data applies to either `push` and `pull` transfers. Finite data transfers cause the transfer -process to transitition to the state `COMPLETED`, once the transmission has finished. For example a transfer of a single +The characterization of the data applies to either `push` and `pull` transfers. Finite data transfers cause the transfer +process to transition to the state `COMPLETED`, once the transmission has finished. For example a transfer of a single file that is hosted and transferred into a cloud storage system. Non-finite data means that once the transfer process request has been accepted by the provider the transfer process is -in the `STARTED` state until it gets terminated by the consumer or the provider. Exampes of Non-finite data are streams -or API endpoins. +in the `STARTED` state until it gets terminated by the consumer or the provider. Examples of Non-finite data are streams +or API endpoints. On the provider side transfer processes can also be terminated by the [policy monitor](../contributor-handbook.md#27-policy-monitor) that -periodically watches over the on going transfer and checks if the +periodically watches over the ongoing transfer and checks if the associated [contract agreement](#5-contract-agreements) still fulfills the contract [policy](#2-policies). ### 7.2 About Data Destinations @@ -1139,14 +1139,14 @@ payload for filtering the datasets: Entities are backed by [stores](./service-layers.md#51-in-memory-stores) for doing CRUD operations. For each entity there is an associated store interface (SPI). Most of the stores SPI have a `query` like method which takes a -`QuerySpec` type as input and returns the matched entities in a collection. Indivitual implementations are then +`QuerySpec` type as input and returns the matched entities in a collection. Individual implementations are then responsible for translating the `QuerySpec` to a proper fetching strategy. The description on how the translation and mapping works will be explained in each implementation. Currently EDC support out of the box: - [In-memory stores](./service-layers.md#51-in-memory-stores) (default implementation). -- [SQL stores](../contributor-handbook.md#29-postgre-sql-persistence) provied as extensions for each store, mostly +- [SQL stores](../contributor-handbook.md#29-postgre-sql-persistence) provided as extensions for each store, mostly tailored for and tested with PostgreSQL. diff --git a/content/en/documentation/for-contributors/control-plane/policy-monitor.md b/content/en/documentation/for-contributors/control-plane/policy-monitor.md index 3bffc4e..15d0cc8 100644 --- a/content/en/documentation/for-contributors/control-plane/policy-monitor.md +++ b/content/en/documentation/for-contributors/control-plane/policy-monitor.md @@ -6,7 +6,7 @@ weight: 10 Some transfer types, once accepted by the `provider`, never reach the `COMPLETED` state. Streaming and HTTP transfers in consumer pull scenario are examples of this. In those scenarios the transfer will remain active (`STARTED`) until it gets terminated either manually by using the transfer processes [management API](./entities.md#7-transfer-processes), or automatically by the policy monitor, if it has been configured in the EDC runtime. -The policy monitor (`PolicyMonitorManager`) is a component that watches over on-going transfers on the provider side and ensures that the associated policies are still valid. The default implementation of the policy monitor tracks the monitored transfer processes in it's own entity `PolicyMonitorEntry` stored in the `PolicyMonitorStore`. +The policy monitor (`PolicyMonitorManager`) is a component that watches over ongoing transfers on the provider side and ensures that the associated policies are still valid. The default implementation of the policy monitor tracks the monitored transfer processes in it's own entity `PolicyMonitorEntry` stored in the `PolicyMonitorStore`. Once a transfer process transition to the `STARTED` state on the provider side, the policy monitor gets notified through the [eventing system](../runtime/service-layers.md#6-events-and-callbacks) of EDC and start tracking transfer process. For each monitored transfer process in the `STARTED` state the policy monitor retrieves the policy associated (through [contract agreement](./entities.md#5-contract-agreements)) and runs the [Policy Engine](./entities.md#22-policy-scopes-and-bindings) using the `policy.monitor` as scope. If the policy is no longer valid, the policy monitor marks the transfer process for termination (`TERMINATING`) and stops tracking it. @@ -19,6 +19,6 @@ Implementors that want a [Policy function](./entities.md#23-policy-evaluation-fu Note that because the policy evaluation happens in the background, the `PolicyContext` does not contain `ParticipantAgent` as context data. This means that the Policy Monitor cannot evaluate policies that involve VerifiableCredentials. -Currently the only information published in the `PolicyContext` available for functions in the `policy.monitor` scope are the [`ContractAgreement`](./entities.md#5-contract-agreements), and the `Instant` at the time of the evaluation. +Currently, the only information published in the `PolicyContext` available for functions in the `policy.monitor` scope are the [`ContractAgreement`](./entities.md#5-contract-agreements), and the `Instant` at the time of the evaluation. A bundled example of a [Policy function](./entities.md#23-policy-evaluation-functions) that runs in the `policy.monitor` scope is the `ContractExpiryCheckFunction` which checks if the [contract agreement](./entities.md#5-contract-agreements) is not expired. diff --git a/content/en/documentation/for-contributors/control-plane/protocol-extensions.md b/content/en/documentation/for-contributors/control-plane/protocol-extensions.md index 9c861d8..ab65150 100644 --- a/content/en/documentation/for-contributors/control-plane/protocol-extensions.md +++ b/content/en/documentation/for-contributors/control-plane/protocol-extensions.md @@ -31,7 +31,7 @@ At the heart of EDC message exchange mechanism lies the `RemoteMessage` interfac Each `RemoteMessage` is: - Delivered to the counter-party using a [RemoteMessageDispatcher](#11-delivering-messages-with-remotemessagedispatcher). -- Received by the counter-party through the protocol implementation (e.g HTTP) and handled by the [protocol services](#11-handling-ingress-messages-with-protocol-services) layer. +- Received by the counter-party through the protocol implementation (e.g. HTTP) and handled by the [protocol services](#11-handling-ingress-messages-with-protocol-services) layer. ### 1.1 Delivering messages with RemoteMessageDispatcher @@ -68,7 +68,7 @@ which handle respectively `Catalog`, `ContractNegotiation` and `TransferProcess` ## 2. DSP protocol implementation -The [Dataspace protocol](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) protocol implementation is available under the `data-protocol/dsp` subfolder in the [Connector](https://github.com/eclipse-edc/Connector) repository and it is identified by the key `dataspace-protocol-http`. +The [Dataspace protocol](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) implementation is available under the `data-protocol/dsp` subfolder in the [Connector](https://github.com/eclipse-edc/Connector) repository and it is identified by the key `dataspace-protocol-http`. It extends the `RemoteMessageDispatcher` with the interface `DspHttpRemoteMessageDispatcher` (`dsp-spi`), which adds an additional method for registering message [handlers](#21-remotemessage-handlers). diff --git a/content/en/documentation/for-contributors/data-plane/_index.md b/content/en/documentation/for-contributors/data-plane/_index.md index b6de082..7c42020 100644 --- a/content/en/documentation/for-contributors/data-plane/_index.md +++ b/content/en/documentation/for-contributors/data-plane/_index.md @@ -169,7 +169,7 @@ public class FileDataSource implements DataSource { } ``` -The relevant method is the `openPartStream`, which will be called for connecting the source and sink. The `openPartStream` returns a `Stream` of `Part` objects, as the `DataSource` can be composed by more that one part (e.g. folders, files, etc.). The `openPartStream` does not actually open a Java `InputStream`, but returns a stream of `Part`s. +The relevant method is the `openPartStream`, which will be called for connecting the source and sink. The `openPartStream` returns a `Stream` of `Part` objects, as the `DataSource` can be composed by more than one part (e.g. folders, files, etc.). The `openPartStream` does not actually open a Java `InputStream`, but returns a stream of `Part`s. Transforming a `Part` into an `InputStream` is the main task of the `DataSource` implementation. In our case the `FileStreamPart#openStream` just returns a `FileInputStream` from the input `File`. @@ -209,7 +209,7 @@ public class FileDataSourceFactory implements DataSourceFactory { For our implementation we express in the `supportedType` method that the the `sourceDataAddress` should be of type `File` and in the `validateRequest` method -that it should contains a property `sourceFile` containing the path of the file to be transferred. +that it should contain a property `sourceFile` containing the path of the file to be transferred. The `FileDataSourceFactory` then should be registered in the `PipelineService`: diff --git a/content/en/documentation/for-contributors/data-plane/data-plane-signaling/_index.md b/content/en/documentation/for-contributors/data-plane/data-plane-signaling/_index.md index af5e4f9..6d214a5 100644 --- a/content/en/documentation/for-contributors/data-plane/data-plane-signaling/_index.md +++ b/content/en/documentation/for-contributors/data-plane/data-plane-signaling/_index.md @@ -31,7 +31,7 @@ control plane and dataplane to control data flows. When the control plane signals to the data plane to start a client pull transfer process, the data plane returns a `DataAddress`. This is only true for consumer-pull transfers - provider push transfers **do not return** a `DataAddress`. This `DataAddress` contains information the client can use to resolve the provider's data plane endpoint. -It also contain an access token (cf. [authorization](#52-public-api-authorization)). +It also contains an access token (cf. [authorization](#52-public-api-authorization)). This `DataAddress` is returned by the provider control plane to the consumer in a `TransferProcessStarted` DSP message. Its purpose is to inform the consumer where they can obtain the data, and which authorization token to use. @@ -185,7 +185,7 @@ consumer can initiate a new process before or after that period. When the `DataPlaneManager` receives a `DataFlowStartMessage` to start the data transmission, it uses the `DataPlaneAuthorizationService` to generate an access token (in JWT format) and a `DataAddress`, that contains the -follwing information: +following information: - `endpoint`: the URL of the public API - `endpointType`: should be `https://w3id.org/idsa/v4.1/HTTP` for HTTP pull transfers @@ -292,7 +292,7 @@ registered data plane. To do that, it simply sends a REST request to the `/v1/da plane. If that returns successfully, the dataplane is still up and running. If not, the control plane will consider the data plane as "unavailable". -In addition to availability, the control plane also records the _capabilities_ of each data plane, i.e. which which +In addition to availability, the control plane also records the _capabilities_ of each data plane, i.e. which source data types and transfer types are supported. Each data plane must declare where it can transfer data _from_ (source type, e.g. `AmazonS3`) and _how_ it can transfer data (transfer type, e.g. `Http-PULL`). diff --git a/content/en/documentation/for-contributors/guidelines/pr-etiquette/_index.md b/content/en/documentation/for-contributors/guidelines/pr-etiquette/_index.md index a11ab90..5417fac 100644 --- a/content/en/documentation/for-contributors/guidelines/pr-etiquette/_index.md +++ b/content/en/documentation/for-contributors/guidelines/pr-etiquette/_index.md @@ -52,7 +52,7 @@ PRs should adhere to the following rules. - No surprise PRs. Before submitting a PR, open a discussion or an issue outlining the planned work and give people time to comment. Unsolicited PRs may get ignored or rejected. - Create focused PRs. Work should be focused on one particular feature or bug. Do not create broad-scoped PRs that - solve multiple issues or span signficant portions of the codebase as they will be rejected outright. + solve multiple issues or span significant portions of the codebase as they will be rejected outright. - Provide a clear PR description and motivation. This makes the reviewer's life much easier. It is also helpful to outline the broad changes that were made, e.g. "Changes the schema of XYZ-Entity: the `age` field changed from `long` to `String`". diff --git a/content/en/documentation/for-contributors/guidelines/release-process.md b/content/en/documentation/for-contributors/guidelines/release-process.md index ad80084..2e67d99 100644 --- a/content/en/documentation/for-contributors/guidelines/release-process.md +++ b/content/en/documentation/for-contributors/guidelines/release-process.md @@ -50,7 +50,7 @@ with the 2 workflows: - if the `source branch` is `main`, it bumps the version number there to the next snapshot version, to let the development cycle flow there - if the `source branch` is not `main`, we're preparing a bugfix version, so the workflow will publish the snapshot version - of the artifacts. no need to do it for `main` because these will already exists as published on every commit on the `main` + of the artifacts. no need to do it for `main` because these will already exist as published on every commit on the `main` branch - [release](https://github.com/eclipse-edc/Release/actions/workflows/release.yml) has as inputs: - use workflow from: always `main` diff --git a/content/en/documentation/for-contributors/postgres-persistence.md b/content/en/documentation/for-contributors/postgres-persistence.md index 24f9ecf..a5e9b0a 100644 --- a/content/en/documentation/for-contributors/postgres-persistence.md +++ b/content/en/documentation/for-contributors/postgres-persistence.md @@ -199,7 +199,7 @@ we must recursively descend into the model graph and resolve the correct SQL exp #### Option 2a: encoding the object Another popular way to store complex objects is to encode them in JSON and store them in a `VARCHAR` column. In -PostgreSQL we use the specific `JSON` type instead of `VARCHAR`. For example, the `TranferProcess` is stored in a table +PostgreSQL, we use the specific `JSON` type instead of `VARCHAR`. For example, the `TranferProcess` is stored in a table called `edc_transfer_process`, its `DataAddress` property is encoded in JSON and stored in a `JSON` field. Querying for `TransferProcess` objects: when mapping the filter expression diff --git a/content/en/documentation/for-contributors/runtime/extension-model.md b/content/en/documentation/for-contributors/runtime/extension-model.md index 43696fe..f3be12b 100644 --- a/content/en/documentation/for-contributors/runtime/extension-model.md +++ b/content/en/documentation/for-contributors/runtime/extension-model.md @@ -123,7 +123,7 @@ Best practices when handling configuration: extension's `initialize()` method. - don't pass the context: it is a code smell if the `ServiceExtensionContext` is passed into a service to resolve config - annotate: every setting should have a `@Setting` annotation -- no magic defaults: default values should be declard as constants in the extension class and documented in the +- no magic defaults: default values should be declared as constants in the extension class and documented in the `@Setting` annotation. - no secrets: configuration is the wrong place to store secrets - naming convention: every config value should start with `edc.` diff --git a/content/en/documentation/for-contributors/runtime/json-ld.md b/content/en/documentation/for-contributors/runtime/json-ld.md index 7419625..bd0d44f 100644 --- a/content/en/documentation/for-contributors/runtime/json-ld.md +++ b/content/en/documentation/for-contributors/runtime/json-ld.md @@ -29,7 +29,7 @@ It's similar on how a `Person` would be represented in JSON, with additional kno The `@id` is used to uniquely identify an object. The `@context` is used to define how [terms](https://www.w3.org/TR/json-ld/#dfn-term) should be interpreted and help -expressing specific identifier with short-hand names instead +expressing specific identifier with shorthand names instead of [IRI](https://datatracker.ietf.org/doc/html/rfc3987#section-2). > Exhausting reserved keywords list and their meaning is @@ -110,7 +110,7 @@ For playing around JSON-LD and processing algorithm the [playground](https://jso ## 1. JSON-LD in EDC EDC uses JSON-LD as primary serialization format at API layer and at runtime EDC manages the objects in their expanded -form, for example when transforming `JsonObject` into EDC entities and and backwards +form, for example when transforming `JsonObject` into EDC entities and backwards in [transformers](programming-primitives.md#2-transformers) or when [validating](#11-json-ld-validation) input `JsonObject` at API level. @@ -129,7 +129,7 @@ Fist EDC embraces different protocols and standards such as: and they all rely on JSON-LD as serialization format. -The second reason is that EDC allows to extends entities like `Asset` with custom properties, and uses JSON-LD as the +The second reason is that EDC allows to extend entities like `Asset` with custom properties, and uses JSON-LD as the way to extend objects with custom namespaces. EDC handles JSON-LD through the `JsonLd` SPI. It supports different operation and configuration for managing JSON-LD in @@ -147,13 +147,13 @@ and allows the configuration of which `@context` and `namespaces` to use when pr scope. For example when using the `JsonLd` service in the management API the `@context` and `namespaces` configured might -differs when using the same service in the `dsp` layer. +differ when using the same service in the `dsp` layer. The `JsonLd` service also can configure cached contexts by allowing to have a local copy of the remote context. This limits the network request required when processing the JSON-LD and reduces the attack surface if the remote host of the context is compromised. -> By default EDC make usage of [`@vocab`](https://www.w3.org/TR/json-ld/#default-vocabulary) for processing input/output +> By default, EDC make usage of [`@vocab`](https://www.w3.org/TR/json-ld/#default-vocabulary) for processing input/output > JSON-LD document. This can provide a default vocabulary for extensible properties. The remote context definition is > available [on W3ID](https://w3id.org/edc/connector/management/v0.0.1). @@ -187,7 +187,7 @@ The input JSON would look like this: } ``` -Even if we don't register a any additional `@context` or `namespace` prefix in the EDC runtime, +Even if we don't register any additional `@context` or `namespace` prefix in the EDC runtime, the [Asset](./entities.md#1-assets) will still be persisted correctly since the JSON-LD gets expanded correctly and stored in the expanded form. @@ -272,8 +272,8 @@ JSON-LD: ## 1.2 Custom Remote Context -An improved version requires developers to draft a context (which should be resolvable with an URL), for example -`http://w3id.org/starwars/context.jsonld`, that contains the terms definition. +An improved version requires developers to draft a context (which should be resolvable with a URL), for example +`http://w3id.org/starwars/context.jsonld`, that contains the term definition. An example of a definition might look like this: @@ -290,7 +290,7 @@ An example of a definition might look like this: } ``` -Then in a an extension the context URL should be registered in the desired scope and cached: +Then in an extension the context URL should be registered in the desired scope and cached: ```java public class MyExtension implements ServiceExtension { @@ -308,7 +308,7 @@ public class MyExtension implements ServiceExtension { } ``` -With this configuration the JSON-LD will be representend without the `sw` prefix, since the terms mapping is defined in +With this configuration the JSON-LD will be represented without the `sw` prefix, since the terms mapping is defined in the remote context `http://w3id.org/starwars/context.jsonld`: ```json @@ -345,8 +345,8 @@ the remote context `http://w3id.org/starwars/context.jsonld`: EDC provides a mechanism to validate JSON-LD objects. The validation phase is typically handled at the network/controller layer. For each entity identified by it's own `@type`, it is possible to register a custom -`Validator` using the registry `JsonObjectValidatorRegistry`. By default EDC provides validation for all the -entities it manages like `Asset`, `ContractDefinition` ..etc. +`Validator` using the registry `JsonObjectValidatorRegistry`. By default, EDC provides validation for all the +entities it manages like `Asset`, `ContractDefinition`, etc. For custom validator it is possible to either implements `Validator` interface (not recommended) or or use the bundled `JsonObjectValidator`, which is a declarative way of configuring a validator for an object through diff --git a/content/en/documentation/for-contributors/runtime/programming-primitives.md b/content/en/documentation/for-contributors/runtime/programming-primitives.md index 0db2538..4e8ff6a 100644 --- a/content/en/documentation/for-contributors/runtime/programming-primitives.md +++ b/content/en/documentation/for-contributors/runtime/programming-primitives.md @@ -25,7 +25,7 @@ EDC is asynchronous by design, which means that processes are processed in such runtime nor the caller. For example starting a contract negotiation is a long-running process and every contract negotiation has to traverse a series of [states](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/contract-negotiation/contract.negotiation.protocol#id-1.2-state-machine), -most of which involve sending remote messages to the counter party. These state transitions are not guaranteed to happen +most of which involve sending remote messages to the counterparty. These state transitions are not guaranteed to happen within a certain time frame, they could take hours or even days. From that it follows that an EDC instance must be regarded as ephemeral (= they can't hold state in memory), so the @@ -200,7 +200,7 @@ about service layers](service-layers.md). ### 2.3 Reporting transformation errors Generally speaking, input validation should be performed by [validators](service-layers.md#2-validators). However, it -is still possible that an object cannot be serialized/deserialized correctly, for example when a property has has the +is still possible that an object cannot be serialized/deserialized correctly, for example when a property has the wrong type, wrong multiplicity, cannot be parsed, unknown property, etc. Those types of errors should be reported to the `TransformerContext`: @@ -240,7 +240,7 @@ var token = tokenGenerationService.generate("my-private-key-id", jtiDecorator, t ``` In the EDC code base the `TokenGenerationService` is not intended to be injectable, because client code typically should -be opinionated with regards to the token technology. +be opinionated with respect to the token technology. ## 4. Token validation and rules diff --git a/content/en/documentation/for-contributors/runtime/service-layers.md b/content/en/documentation/for-contributors/runtime/service-layers.md index a595c60..936465c 100644 --- a/content/en/documentation/for-contributors/runtime/service-layers.md +++ b/content/en/documentation/for-contributors/runtime/service-layers.md @@ -180,7 +180,7 @@ public void initialize(ServiceExtensionContext context) { ``` This registers the request filter for the web context, and registers the authentication service within the request -filter. That way, whenever a HTTP request hits the `"yourcontext"` servlet container, the request filter gets invoked, +filter. That way, whenever an HTTP request hits the `"yourcontext"` servlet container, the request filter gets invoked, delegating to the `SuperCustomAuthService` instance. @@ -277,7 +277,7 @@ is referenced by a `ContractNegotiation`, and - if not - delete the asset. For t services, an `AssetIndex` and a `ContractNegotiationStore`. Likewise, when creating assets, the `AssetService` would first perform some validation, then create the asset (again -using the `AssetIndex`) and the emit an [event](#6-events-and-callbacks). +using the `AssetIndex`) and then emit an [event](#6-events-and-callbacks). Note that the validation mentioned here is different from [API validators](#2-validators). API validators only validate the _structure_ of a JSON object, so check if mandatory fields are missing etc., whereas _service validation_ @@ -317,7 +317,7 @@ Typically, stores fulfill the following contract: ### 5.1 In-Memory stores -By default and unless configured otherwise, EDC provides in-memory store +By default, and unless configured otherwise, EDC provides in-memory store implementations [by default](./dependency-injection.md#12-provide-defaults). These are light-weight, thread-safe `Map` -based implementations, that are intended for **testing, demonstration and tutorial purposes only**. diff --git a/content/en/documentation/for-contributors/testing.md b/content/en/documentation/for-contributors/testing.md index 1a203ad..c46dded 100644 --- a/content/en/documentation/for-contributors/testing.md +++ b/content/en/documentation/for-contributors/testing.md @@ -217,7 +217,7 @@ testImplementation(testFixtures("org.eclipse.edc:management-api-test-fixtures: