You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2023/04/16 03:44:23 UTC
[incubator-opendal] 01/01: docs: Add OpenDAL VISION
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch add-vision
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 475cc11dcfb245a62a6115d1234bef8965009711
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Sun Apr 16 11:44:07 2023 +0800
docs: Add OpenDAL VISION
Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
.asf.yaml | 2 +-
bindings/c/include/opendal.h | 160 ++++++++++++++++++++---------------------
core/README.md | 2 +-
core/src/lib.rs | 2 +-
website/docs/index.md | 76 ++++++++++++++++++++
website/docs/overview.md | 4 --
website/{ => docs}/sidebars.js | 27 +------
website/docs/vision.md | 54 ++++++++++++++
website/docusaurus.config.js | 6 +-
9 files changed, 218 insertions(+), 115 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index c6ff7d55..730f0b35 100644
--- a/.asf.yaml
+++ b/.asf.yaml
@@ -17,7 +17,7 @@
# NOTE: All configurations could be found here: https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features
github:
- description: "Apache OpenDAL: Access data freely, painlessly, and efficiently."
+ description: "Apache OpenDAL: access data freely."
homepage: https://opendal.apache.org
labels:
- rust
diff --git a/bindings/c/include/opendal.h b/bindings/c/include/opendal.h
index e177cb71..f4ad4704 100644
--- a/bindings/c/include/opendal.h
+++ b/bindings/c/include/opendal.h
@@ -17,66 +17,66 @@
* under the License.
*/
+
#ifndef _OPENDAL_H
#define _OPENDAL_H
-#include <stdbool.h>
-#include <stddef.h>
#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
/*
The error code for opendal APIs in C binding
*/
typedef enum opendal_code {
- /*
- All is well
- */
- OPENDAL_OK,
- /*
- General error
- */
- OPENDAL_ERROR,
- /*
- returning it back. For example, s3 returns an internal service error.
- */
- OPENDAL_UNEXPECTED,
- /*
- Underlying service doesn't support this operation.
- */
- OPENDAL_UNSUPPORTED,
- /*
- The config for backend is invalid.
- */
- OPENDAL_CONFIG_INVALID,
- /*
- The given path is not found.
- */
- OPENDAL_NOT_FOUND,
- /*
- The given path doesn't have enough permission for this operation
- */
- OPENDAL_PERMISSION_DENIED,
- /*
- The given path is a directory.
- */
- OPENDAL_IS_A_DIRECTORY,
- /*
- The given path is not a directory.
- */
- OPENDAL_NOT_A_DIRECTORY,
- /*
- The given path already exists thus we failed to the specified operation on
- it.
- */
- OPENDAL_ALREADY_EXISTS,
- /*
- Requests that sent to this path is over the limit, please slow down.
- */
- OPENDAL_RATE_LIMITED,
- /*
- The given file paths are same.
- */
- OPENDAL_IS_SAME_FILE,
+ /*
+ All is well
+ */
+ OPENDAL_OK,
+ /*
+ General error
+ */
+ OPENDAL_ERROR,
+ /*
+ returning it back. For example, s3 returns an internal service error.
+ */
+ OPENDAL_UNEXPECTED,
+ /*
+ Underlying service doesn't support this operation.
+ */
+ OPENDAL_UNSUPPORTED,
+ /*
+ The config for backend is invalid.
+ */
+ OPENDAL_CONFIG_INVALID,
+ /*
+ The given path is not found.
+ */
+ OPENDAL_NOT_FOUND,
+ /*
+ The given path doesn't have enough permission for this operation
+ */
+ OPENDAL_PERMISSION_DENIED,
+ /*
+ The given path is a directory.
+ */
+ OPENDAL_IS_A_DIRECTORY,
+ /*
+ The given path is not a directory.
+ */
+ OPENDAL_NOT_A_DIRECTORY,
+ /*
+ The given path already exists thus we failed to the specified operation on it.
+ */
+ OPENDAL_ALREADY_EXISTS,
+ /*
+ Requests that sent to this path is over the limit, please slow down.
+ */
+ OPENDAL_RATE_LIMITED,
+ /*
+ The given file paths are same.
+ */
+ OPENDAL_IS_SAME_FILE,
} opendal_code;
/*
@@ -121,7 +121,7 @@ typedef struct BlockingOperator BlockingOperator;
to check its validity by native boolean operator.
e.g. you could check by (!ptr) on a [`opendal_operator_ptr`]
*/
-typedef const struct BlockingOperator* opendal_operator_ptr;
+typedef const struct BlockingOperator *opendal_operator_ptr;
/*
The [`opendal_bytes`] type is a C-compatible substitute for [`Vec`]
@@ -130,8 +130,8 @@ typedef const struct BlockingOperator* opendal_operator_ptr;
to free the heap memory to avoid memory leak.
*/
typedef struct opendal_bytes {
- const uint8_t* data;
- uintptr_t len;
+ const uint8_t *data;
+ uintptr_t len;
} opendal_bytes;
/*
@@ -141,8 +141,8 @@ typedef struct opendal_bytes {
and the error code is NOT OPENDAL_OK.
*/
typedef struct opendal_result_read {
- struct opendal_bytes* data;
- enum opendal_code code;
+ struct opendal_bytes *data;
+ enum opendal_code code;
} opendal_result_read;
/*
@@ -151,8 +151,8 @@ typedef struct opendal_result_read {
corresponding error code.
*/
typedef struct opendal_result_is_exist {
- bool is_exist;
- enum opendal_code code;
+ bool is_exist;
+ enum opendal_code code;
} opendal_result_is_exist;
#ifdef __cplusplus
@@ -160,19 +160,17 @@ extern "C" {
#endif // __cplusplus
/*
- Returns a result type [`opendal_result_op`], with operator_ptr. If the
- construction succeeds the error is nullptr, otherwise it contains the error
- information.
+ Returns a result type [`opendal_result_op`], with operator_ptr. If the construction succeeds
+ the error is nullptr, otherwise it contains the error information.
# Safety
It is [safe] under two cases below
- * The memory pointed to by `scheme` must contain a valid nul terminator at the
- end of the string.
- * The `scheme` points to NULL, this function simply returns you a null
- opendal_operator_ptr
+ * The memory pointed to by `scheme` must contain a valid nul terminator at the end of
+ the string.
+ * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr
*/
-opendal_operator_ptr opendal_operator_new(const char* scheme);
+opendal_operator_ptr opendal_operator_new(const char *scheme);
/*
Free the allocated operator pointed by [`opendal_operator_ptr`]
@@ -180,22 +178,22 @@ opendal_operator_ptr opendal_operator_new(const char* scheme);
void opendal_operator_free(opendal_operator_ptr op_ptr);
/*
- Write the data into the path blockingly by operator, returns the error code
- OPENDAL_OK if succeeds, others otherwise
+ Write the data into the path blockingly by operator, returns the error code OPENDAL_OK
+ if succeeds, others otherwise
# Safety
It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ the string.
# Panic
* If the `path` points to NULL, this function panics
*/
enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr,
- const char* path,
- struct opendal_bytes bytes);
+ const char *path,
+ struct opendal_bytes bytes);
/*
Read the data out from path into a [`Bytes`] blockingly by operator, returns
@@ -205,15 +203,15 @@ enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr,
# Safety
It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ the string.
# Panic
* If the `path` points to NULL, this function panics
*/
-struct opendal_result_read opendal_operator_blocking_read(
- opendal_operator_ptr op_ptr, const char* path);
+struct opendal_result_read opendal_operator_blocking_read(opendal_operator_ptr op_ptr,
+ const char *path);
/*
Check whether the path exists.
@@ -226,20 +224,20 @@ struct opendal_result_read opendal_operator_blocking_read(
# Safety
It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ the string.
# Panic
* If the `path` points to NULL, this function panics
*/
-struct opendal_result_is_exist opendal_operator_is_exist(
- opendal_operator_ptr op_ptr, const char* path);
+struct opendal_result_is_exist opendal_operator_is_exist(opendal_operator_ptr op_ptr,
+ const char *path);
/*
Frees the heap memory used by the [`opendal_bytes`]
*/
-void opendal_bytes_free(const struct opendal_bytes* self);
+void opendal_bytes_free(const struct opendal_bytes *self);
#ifdef __cplusplus
} // extern "C"
diff --git a/core/README.md b/core/README.md
index 7640e64e..8bbce48e 100644
--- a/core/README.md
+++ b/core/README.md
@@ -8,7 +8,7 @@
[chat]: https://img.shields.io/discord/1081052318650339399
[discord]: https://discord.gg/XQy8yGR2dg
-**Open** **D**ata **A**ccess **L**ayer: Access data freely, painlessly, and efficiently
+**Open** **D**ata **A**ccess **L**ayer: access data freely.
- Documentation: [stable](https://docs.rs/opendal/) | [main](https://opendal.apache.org/docs/rust/opendal/)
- [Release notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html)
diff --git a/core/src/lib.rs b/core/src/lib.rs
index b5df5aea..bc361738 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-//! OpenDAL is the Open Data Access Layer to **freely**, **painlessly**, and **efficiently** access data.
+//! OpenDAL is the Open Data Access Layer to **freely** access data.
//!
//! - Documentation: All docs are carried byself, visit [`docs`] for more.
//! - Services: All supported services could be found at [`services`].
diff --git a/website/docs/index.md b/website/docs/index.md
new file mode 100644
index 00000000..2d4a3295
--- /dev/null
+++ b/website/docs/index.md
@@ -0,0 +1,76 @@
+---
+title: Overview
+sidebar_position: 1
+---
+
+**Open** **D**ata **A**ccess **L**ayer: Access data freely.
+
+
+
+## Quickstart
+
+### Rust
+
+```rust
+use opendal::Result;
+use opendal::layers::LoggingLayer;
+use opendal::services;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ // Pick a builder and configure it.
+ let mut builder = services::S3::default();
+ builder.bucket("test");
+
+ // Init an operator
+ let op = Operator::new(builder)?
+ // Init with logging layer enabled.
+ .layer(LoggingLayer::default())
+ .finish();
+
+ // Write data
+ op.write("hello.txt", "Hello, World!").await?;
+
+ // Read data
+ let bs = op.read("hello.txt").await?;
+
+ // Fetch metadata
+ let meta = op.stat("hello.txt").await?;
+ let mode = meta.mode();
+ let length = meta.content_length();
+
+ // Delete
+ op.delete("hello.txt").await?;
+
+ Ok(())
+}
+```
+
+### Python
+
+```python
+import asyncio
+
+async def main():
+ op = opendal.AsyncOperator("fs", root="/tmp")
+ await op.write("test.txt", b"Hello World")
+ print(await op.read("test.txt"))
+
+asyncio.run(main())
+```
+
+### Node.js
+
+```js
+import { Operator } from "opendal";
+
+async function main() {
+ const op = new Operator("fs", { root: "/tmp" });
+ await op.write("test", "Hello, World!");
+ const bs = await op.read("test");
+ console.log(new TextDecoder().decode(bs));
+ const meta = await op.stat("test");
+ console.log(`contentLength: ${meta.contentLength}`);
+}
+```
diff --git a/website/docs/overview.md b/website/docs/overview.md
deleted file mode 100644
index 42956286..00000000
--- a/website/docs/overview.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_position: 1
-title: Overview
----
diff --git a/website/sidebars.js b/website/docs/sidebars.js
similarity index 59%
rename from website/sidebars.js
rename to website/docs/sidebars.js
index 850844c2..7704508a 100644
--- a/website/sidebars.js
+++ b/website/docs/sidebars.js
@@ -17,36 +17,11 @@
* under the License.
*/
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
- // By default, Docusaurus generates a sidebar from the docs folder structure
- tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
- // But you can create a sidebar manually
- /*
- tutorialSidebar: [
- 'intro',
- 'hello',
- {
- type: 'category',
- label: 'Tutorial',
- items: ['tutorial-basics/create-a-document'],
- },
- ],
- */
+ docs: [{ type: 'autogenerated', dirName: '.' }],
};
module.exports = sidebars;
diff --git a/website/docs/vision.md b/website/docs/vision.md
new file mode 100644
index 00000000..babf2651
--- /dev/null
+++ b/website/docs/vision.md
@@ -0,0 +1,54 @@
+---
+title: Vision
+sidebar_position: 2
+---
+
+OpenDAL VISION: **access data freely**.
+
+### Free from services
+
+OpenDAL must enable users to access various storage services ranging from `s3` to `dropbox` via it's own native API. It should provide a unified API for accessing all these services.
+
+- Add support for google drive: Good, it allows users to access and manage their data on the google drive.
+- Add support for oss via native API: Good, users can utilize Aliyun's RAM support.
+- Add support for [supabase storage](https://supabase.com/docs/guides/storage): Good, users can visit supabase sotrage now!
+
+
+- Add support for gcs via XML API: Bad, gcs has native JSON API which more powerful
+- Add support for MySQL/PostgreSQL: Bad, relational DBMS provides data types such as BLOB, but they are often not used as a storage service.
+
+### Free from implementations
+
+OpenDAL needs to separate the various implementation details of services and enables users to write identical logic for different services.
+
+- Add a new capability to indicate whether or not `presign` is supported: Good, users can now write logic based on the `can_presign` option.
+- Add a `default_storage_class` configuration for the S3 service: Good, configuration is specific to the s3 service.
+- Add an option for `content_type` in the `write` operation: Good, it aligns with HTTP standards.
+
+
+- Add a new option in read for `storage_class`: Bad, as different services could have varying values for this parameter.
+
+### Free to integrate
+
+OpenDAL needs to be integrated with different systems.
+
+- Add python binding: Good, users from `python` can use OpenDAL.
+- Add object_store integration: Good, users of `object_store` can adopt OpenDAL.
+
+
+- Rewrite OpenDAL in Golang: Good idea itself, but not related to OpenDAL.
+
+### Free to zero cost
+
+OpenDAL needs to implement features in zero cost way which means:
+
+- Users don't need to pay cost for not used features.
+- Users can't write better implementation for used features.
+
+For examples:
+
+- Add `layer` support: Good, users can add logging/metrics/tracing in zero cost way.
+- Implement `seek` for Reader: Good, users can't write better `seek` support, they all need to pay the same cost.
+
+
+- Add `Arc` for metadata: Bad, users may only need to use metadata once and never clone it. For those who do want this feature, they can add `Arc` themselves
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 29eb75b3..680abdb2 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -50,7 +50,7 @@ const config = {
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
- sidebarPath: require.resolve('./sidebars.js'),
+ sidebarPath: require.resolve('./docs/sidebars.js'),
editUrl:
'https://github.com/apache/incubator-opendal/website/',
showLastUpdateAuthor: true,
@@ -90,6 +90,10 @@ const config = {
position: 'right',
label: 'Documentation',
items: [
+ {
+ type: 'html',
+ value: '<a class="dropdown__link" href="/docs">General</a>'
+ },
{
type: 'html',
value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust</a>'