diff --git a/CHANGELOG.md b/CHANGELOG.md index 50fc883..19cff03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,18 @@ All notable changes to `cotto` will be documented in this file. +## v1.2.1 - 2024-10-21 +- Tested and runnable with Otto 41.1.3 +- Adjustments in READMEs and help text + +**Full Changelog**: https://github.com/rechtlogisch/cotto/commits/v1.2.1 + +## v1.2.0 - 2024-10-18 +- Utilizes Otto 40.3.4 +- Adds flag -m, which incorporates a newly introduced simplified function to download objects in-memory, instead of downloading them blockwise + +**Full Changelog**: https://github.com/rechtlogisch/cotto/commits/v1.2.0 + ## v1.1.0 - 2024-07-29 - Utilizes Otto 40.2.8 - Supports most security tokens (Abholzertifikat not implemented in this demo) diff --git a/README.md b/README.md index 266a13b..d388c47 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,14 @@ Notice: This demo is **not intended for productive usage**! ELSTER introduced on May 27th, 2024, a new library called Otto, which can be used to download objects from OTTER (Object Storage in ELSTER). The reason why ELSTER introduced the project and library is, that the current solution hit its limits. Otto was introduced together with a new version of Datenabholung. -The currently available way of data retrieval with ERiC will be replaced client-side in ERiC version 41 (end November 2024; only Datenabholung v31 will be available) and server-side with the planned yearly minimal version increase mid-April 2025 (exact date TBA in 2025; only ERiC >= v41 with Datenabholung v31 can be used after that date). Therefore, a majority of software developers using currently ERiC Datenabholung will have to implement Otto in production by April 2025. +The currently available way of data retrieval with ERiC will be replaced client-side in ERiC version 41 (on November 25th, 2024; only Datenabholung v31 will be available) and server-side with the planned yearly minimal version increase mid-April 2025 (exact date TBA in 2025; only ERiC >= v41 with Datenabholung v31 can be used after that date). Therefore, a majority of software developers using currently ERiC Datenabholung will have to implement Otto in production by April 2025. ## Usage ```bash ./cotto -u objectUuid UUID of object to download (mandatory) + -m size Allocate provided Bytes of memory and download object in-memory (optional, max: 10485760 Bytes), cf. Download modes -e extension Set filename extension of downloaded content [default: "txt"] -p password Password for certificate [default: "123456"] -f Force file overwriting [default: false] @@ -80,6 +81,14 @@ Hint: The downloaded result will be saved in the same directory as `cotto`, unle All supported environment variables are listed in [`.env.example`](.env.example). Feel free to copy them to `.env`, adjust accordingly and source for usage. +## Download modes + +The demo showcases two methods for downloading objects: blockwise (default) and in-memory. Otter and Otto operates by design in a memory efficient way - streaming data and forwarding it to the desired storage blockwise. That is the optimal and memory-efficient way for big files. ELSTER engineers wrapped all needed calls and the download workflow in one function `OttoDatenAbholen()`, which simplifies the implementation and stores the complete object temporarily in-memory. + +This demo can operate in both modes. To download in-memory add option `-m` with a value exceeding `0` and not exceeding `10485760` Bytes (10 MiB). It is recommended to use the in-memory mode with objects where the final size is known and not exceeding (an arbitraly set) size of 10485760 Bytes. + +Hint: `-m` sets the minimal allocated memory size. When the object is bigger then the set size - Otto allocates as much as need and as much as available memory. Use at your own risk. + ## Docker A simple [Dockerfile](Dockerfile) is included. You can use `make docker-build` and `make docker-cotto` to build and run `cotto` in a container. diff --git a/certificate/.gitignore b/certificate/.gitignore index bf27f31..7c9d611 100644 --- a/certificate/.gitignore +++ b/certificate/.gitignore @@ -1,3 +1,3 @@ * !.gitignore -!.gitkeep +!README.md diff --git a/certificate/.gitkeep b/certificate/.gitkeep deleted file mode 100644 index 8e66695..0000000 --- a/certificate/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -Run `./get-test-certificate.sh` or copy your .pfx-file here manually. diff --git a/certificate/README.md b/certificate/README.md new file mode 100644 index 0000000..efa27d7 --- /dev/null +++ b/certificate/README.md @@ -0,0 +1 @@ +Run `../get-test-certificate.sh` or copy your .pfx-file|CEZ here manually. diff --git a/cotto.cpp b/cotto.cpp index 2b1c6cf..195af45 100644 --- a/cotto.cpp +++ b/cotto.cpp @@ -237,7 +237,7 @@ int main(const int argc, char *argv[]) { std::cerr << "Usage:" << std::endl; std::cerr << "" << argv[0] << std::endl; std::cerr << " -u objectUuid\t\tUUID of object to download (mandatory)" << std::endl; - std::cerr << " -m size\t\tDownload object in-memory and allocate provided Bytes of memory (optional, max: 10485760 Bytes), when not provided or exceeds max download blockwise" << std::endl; + std::cerr << " -m size\t\tAllocate provided Bytes of memory and download object in-memory (optional, max: 10485760 Bytes), when not provided or exceeds max download blockwise" << std::endl; std::cerr << " -e extension\t\tSet filename extension of downloaded content [optional, default: \"txt\"]" << std::endl; std::cerr << " -p password\t\tPassword for certificate [optional, default: \"123456\"]" << std::endl; std::cerr << " -f\t\t\tForce file overwriting [optional, default: false]" << std::endl; diff --git a/rechtlogisch-cotto-banner.png b/rechtlogisch-cotto-banner.png index 99b618f..e0a4be9 100644 Binary files a/rechtlogisch-cotto-banner.png and b/rechtlogisch-cotto-banner.png differ diff --git a/vendor/.gitignore b/vendor/.gitignore index bf27f31..7c9d611 100644 --- a/vendor/.gitignore +++ b/vendor/.gitignore @@ -1,3 +1,3 @@ * !.gitignore -!.gitkeep +!README.md diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 0000000..b70458c --- /dev/null +++ b/vendor/README.md @@ -0,0 +1,9 @@ +Place here: + + - (lib)otto.{so|dylib|dll} + - (lib)eSigner.{so|dylib|dll} + - otto.h + - otto_statuscode.h + - otto_types.h + +originating from [ERiC-*.jar](https://www.elster.de/elsterweb/entwickler/infoseite/eric)