tracdap-runtime 0.5.30__py3-none-any.whl → 0.6.0__py3-none-any.whl

tracdap/rt/_plugins/storage_gcp.py

@@ -0,0 +1,183 @@
+#  Copyright 2023 Accenture Global Solutions Limited
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import typing as tp
+import datetime as dt
+
+import tracdap.rt.exceptions as ex
+
+# Import storage interfaces
+import tracdap.rt.ext.plugins as plugins
+from tracdap.rt.ext.storage import *
+
+from pyarrow import fs as pa_fs
+
+# Set of common helpers across the core plugins (do not reference rt._impl)
+from . import _helpers
+
+
+try:
+    # These dependencies are provided by the optional [gcp] feature
+    # For local development, pip install -r requirements_plugins.txt
+    import google.cloud.storage as gcs  # noqa
+    import gcsfs  # noqa
+    __gcp_available = True
+except ImportError:
+    gcs = None
+    gcsfs = None
+    __gcp_available = False
+
+
+class GcpStorageProvider(IStorageProvider):
+
+    BUCKET_PROPERTY = "bucket"
+    PREFIX_PROPERTY = "prefix"
+    REGION_PROPERTY = "region"
+    ENDPOINT_PROPERTY = "endpoint"
+
+    CREDENTIALS_PROPERTY = "credentials"
+    CREDENTIALS_ADC = "adc"
+    CREDENTIALS_ACCESS_TOKEN = "access_token"
+
+    ACCESS_TOKEN = "accessToken"
+    ACCESS_TOKEN_EXPIRY = "accessTokenExpiry"
+    ACCESS_TOKEN_EXPIRY_DEFAULT = 3600
+
+    RUNTIME_FS_PROPERTY = "runtimeFs"
+    RUNTIME_FS_AUTO = "auto"
+    RUNTIME_FS_ARROW = "arrow"
+    RUNTIME_FS_FSSPEC = "fsspec"
+    RUNTIME_FS_DEFAULT = RUNTIME_FS_AUTO
+
+    ARROW_CLIENT_ARGS = {
+        REGION_PROPERTY: "default_bucket_location",
+        ENDPOINT_PROPERTY: "endpoint_override"
+    }
+
+    FSSPEC_CLIENT_ARGS = {
+        REGION_PROPERTY: "default_location",
+        ENDPOINT_PROPERTY: "endpoint_url"
+    }
+
+    try:
+        __arrow_available = pa_fs.GcsFileSystem is not None
+    except ImportError:
+        __arrow_available = False
+
+    def __init__(self, properties: tp.Dict[str, str]):
+
+        self._log = _helpers.logger_for_object(self)
+        self._properties = properties
+
+        self._runtime_fs = _helpers.get_plugin_property(
+            properties, self.RUNTIME_FS_PROPERTY) \
+            or self.RUNTIME_FS_DEFAULT
+
+    def has_arrow_native(self) -> bool:
+        return True
+
+    def get_arrow_native(self) -> pa_fs.SubTreeFileSystem:
+
+        if self._runtime_fs == self.RUNTIME_FS_AUTO:
+            gcs_fs = self.create_arrow() if self.__arrow_available else self.create_fsspec()
+        elif self._runtime_fs == self.RUNTIME_FS_ARROW:
+            gcs_fs = self.create_arrow()
+        elif self._runtime_fs == self.RUNTIME_FS_FSSPEC:
+            gcs_fs = self.create_fsspec()
+        else:
+            message = f"Requested runtime FS [{self._runtime_fs}] is not available for GCP storage"
+            self._log.error(message)
+            raise ex.EStartup(message)
+
+        bucket = _helpers.get_plugin_property(self._properties, self.BUCKET_PROPERTY)
+        prefix = _helpers.get_plugin_property(self._properties, self.PREFIX_PROPERTY)
+
+        if bucket is None or len(bucket.strip()) == 0:
+            message = f"Missing required config property [{self.BUCKET_PROPERTY}] for GCP storage"
+            self._log.error(message)
+            raise ex.EConfigParse(message)
+
+        root_path = f"{bucket}/{prefix}" if prefix else bucket
+
+        return pa_fs.SubTreeFileSystem(root_path, gcs_fs)
+
+    def create_arrow(self) -> pa_fs.FileSystem:
+
+        gcs_arrow_args = self.setup_client_args(self.ARROW_CLIENT_ARGS)
+
+        return pa_fs.GcsFileSystem(**gcs_arrow_args)
+
+    def create_fsspec(self) -> pa_fs.FileSystem:
+
+        gcs_fsspec_args = self.setup_client_args(self.FSSPEC_CLIENT_ARGS)
+        gcs_fsspec = gcsfs.GCSFileSystem(**gcs_fsspec_args)
+
+        return pa_fs.PyFileSystem(pa_fs.FSSpecHandler(gcs_fsspec))
+
+    def setup_client_args(self, arg_mapping: tp.Dict[str, str]) -> tp.Dict[str, tp.Any]:
+
+        client_args = dict()
+
+        region = _helpers.get_plugin_property(self._properties, self.REGION_PROPERTY)
+        endpoint = _helpers.get_plugin_property(self._properties, self.ENDPOINT_PROPERTY)
+
+        if region is not None:
+            region_key = arg_mapping[self.REGION_PROPERTY]
+            client_args[region_key] = region
+
+        if endpoint is not None:
+            endpoint_key = arg_mapping[self.ENDPOINT_PROPERTY]
+            client_args[endpoint_key] = endpoint
+
+        credentials = self.setup_credentials()
+        client_args.update(credentials)
+
+        return client_args
+
+    def setup_credentials(self):
+
+        # Only default (Google ADC) mechanism is supported
+        # Arrow GCP FS does also support access tokens, but ADC is probably all we ever need
+
+        mechanism = _helpers.get_plugin_property(self._properties, self.CREDENTIALS_PROPERTY)
+
+        if mechanism is None or len(mechanism) == 0 or mechanism.lower() == self.CREDENTIALS_ADC:
+            self._log.info(f"Using [{self.CREDENTIALS_ADC}] credentials mechanism")
+            return dict()
+
+        if mechanism == self.CREDENTIALS_ACCESS_TOKEN:
+
+            self._log.info(f"Using [{self.CREDENTIALS_ACCESS_TOKEN}] credentials mechanism")
+
+            access_token = _helpers.get_plugin_property(self._properties, self.ACCESS_TOKEN)
+            access_token_expiry = _helpers.get_plugin_property(self._properties, self.ACCESS_TOKEN_EXPIRY)
+
+            if access_token is None or len(access_token.strip()) == 0:
+                message = f"Missing required config property [{self.ACCESS_TOKEN}] for GCP storage"
+                raise ex.EConfigParse(message)
+
+            if access_token_expiry is None:
+                access_token_expiry = self.ACCESS_TOKEN_EXPIRY_DEFAULT
+
+            expiry_timestamp = dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=float(access_token_expiry))
+
+            return {"access_token": access_token, "credential_token_expiration": expiry_timestamp}
+
+        message = f"Unrecognised credentials mechanism: [{mechanism}]"
+        self._log.error(message)
+        raise ex.EStartup(message)
+
+
+if __gcp_available:
+    plugins.PluginManager.register_plugin(IStorageProvider, GcpStorageProvider, ["GCS"])

tracdap/rt/_plugins/storage_local.py

@@ -13,6 +13,9 @@
 #  limitations under the License.
 
 import datetime as dt
+import os
+import re
+import sys
 import typing as tp
 import pathlib
 
@@ -23,27 +26,61 @@ import tracdap.rt.exceptions as ex
 import tracdap.rt.ext.plugins as plugins
 from tracdap.rt.ext.storage import *
 
+import pyarrow.fs as afs
+
 # Set of common helpers across the core plugins (do not reference rt._impl)
 from . import _helpers
 
-# TODO: Remove dependencies on internal implementation details
-import tracdap.rt._impl.storage as _storage
-
 
-class LocalFileStorage(IFileStorage):
+class LocalStorageProvider(IStorageProvider):
 
     ROOT_PATH_PROPERTY = "rootPath"
 
-    def __init__(self, config: cfg.PluginConfig, options: dict = None):
+    RUNTIME_FS_PROPERTY = "runtimeFs"
+    RUNTIME_FS_AUTO = "auto"
+    RUNTIME_FS_ARROW = "arrow"
+    RUNTIME_FS_PYTHON = "python"
+    RUNTIME_FS_DEFAULT = RUNTIME_FS_AUTO
+
+    def __init__(self, properties: tp.Dict[str, str]):
 
         self._log = _helpers.logger_for_object(self)
-        self._properties = config.properties
+        self._properties = properties
+
+        self._root_path = self.check_root_path(self._properties, self._log)
+
+        self._runtime_fs = _helpers.get_plugin_property(
+            properties, self.RUNTIME_FS_PROPERTY) \
+            or self.RUNTIME_FS_DEFAULT
+
+    def has_arrow_native(self) -> bool:
+        return self._runtime_fs in [self.RUNTIME_FS_ARROW, self.RUNTIME_FS_AUTO]
+
+    def has_file_storage(self) -> bool:
+        return self._runtime_fs == self.RUNTIME_FS_PYTHON
 
-        root_path_config = _helpers.get_plugin_property(self._properties, self.ROOT_PATH_PROPERTY)
+    def get_arrow_native(self) -> afs.SubTreeFileSystem:
+        root_fs = afs.LocalFileSystem()
+        return afs.SubTreeFileSystem(str(self._root_path), root_fs)
+
+    def get_file_storage(self) -> IFileStorage:
+
+        config = cfg.PluginConfig()
+        config.protocol = "LOCAL"
+        config.properties = self._properties
+
+        options = dict()
+
+        return LocalFileStorage(config, options)
+
+    @classmethod
+    def check_root_path(cls, properties, log):
+
+        root_path_config = _helpers.get_plugin_property(properties, cls.ROOT_PATH_PROPERTY)
 
         if not root_path_config or root_path_config.isspace():
             err = f"Storage root path not set"
-            self._log.error(err)
+            log.error(err)
             raise ex.EStorageRequest(err)
 
         supplied_root = pathlib.Path(root_path_config)
@@ -53,17 +90,58 @@ class LocalFileStorage(IFileStorage):
 
         else:
             err = f"Relative path not allowed for storage root [{supplied_root}]"
-            self._log.error(err)
+            log.error(err)
             raise ex.EStorageConfig(err)
 
         try:
-            self._root_path = absolute_root.resolve(strict=True)
+            return absolute_root.resolve(strict=True)
 
         except FileNotFoundError as e:
             err = f"Storage root path does not exist: [{absolute_root}]"
-            self._log.error(err)
+            log.error(err)
             raise ex.EStorageRequest(err) from e
 
+
+plugins.PluginManager.register_plugin(IStorageProvider, LocalStorageProvider, ["LOCAL", "file"])
+
+
+# ----------------------------------------------------------------------------------------------------------------------
+# CUSTOM IMPLEMENTATION FOR LOCAL STORAGE
+# ----------------------------------------------------------------------------------------------------------------------
+
+# This is the old implementation that was used before Arrow native was made available
+# It is likely to be removed in a future release
+
+
+class _StreamResource(tp.BinaryIO):  # noqa
+
+    def __init__(self, ctx_mgr, close_func):
+        self.__ctx_mgr = ctx_mgr
+        self.__close_func = close_func
+
+    def __getitem__(self, item):
+        return self.__ctx_mgr.__getitem__(item)
+
+    def __enter__(self):
+        return self.__ctx_mgr.__enter__()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            self.__close_func()
+        finally:
+            self.__ctx_mgr.__exit__(exc_type, exc_val, exc_tb)
+
+
+class LocalFileStorage(IFileStorage):
+
+    def __init__(self, config: cfg.PluginConfig, options: dict = None):
+
+        self._log = _helpers.logger_for_object(self)
+        self._properties = config.properties
+        self._options = options  # Not used
+
+        self._root_path = LocalStorageProvider.check_root_path(self._properties, self._log)
+
     def _get_root(self):
         return self._root_path
 
@@ -74,13 +152,26 @@ class LocalFileStorage(IFileStorage):
 
     def _exists(self, storage_path: str) -> bool:
 
-        item_path = self._root_path / storage_path
+        item_path = self._resolve_path(storage_path, "EXISTS", True)
         return item_path.exists()
 
     def size(self, storage_path: str) -> int:
 
         operation = f"SIZE [{storage_path}]"
-        return self._error_handling(operation, lambda: self._stat(storage_path).size)
+        return self._error_handling(operation, lambda: self._size(storage_path))
+
+    def _size(self, storage_path: str) -> int:
+
+        item_path = self._resolve_path(storage_path, "SIZE", True)
+
+        if not item_path.exists():
+            raise ex.EStorageRequest(f"Storage path does not exist: SIZE [{storage_path}]")
+
+        if not item_path.is_file():
+            raise ex.EStorageRequest(f"Storage path is not a file: SIZE [{storage_path}]")
+
+        os_stat = item_path.stat()
+        return os_stat.st_size
 
     def stat(self, storage_path: str) -> FileStat:
 
@@ -89,63 +180,100 @@ class LocalFileStorage(IFileStorage):
 
     def _stat(self, storage_path: str) -> FileStat:
 
-        item_path = self._root_path / storage_path
+        item_path = self._resolve_path(storage_path, "STAT", True)
         os_stat = item_path.stat()
 
+        return self._os_to_trac_stat(item_path, os_stat)
+
+    def _os_to_trac_stat(self, item_path: pathlib.Path, os_stat: os.stat_result):
+
+        file_name = "." if item_path == self._root_path else item_path.name
+
         file_type = FileType.FILE if item_path.is_file() \
             else FileType.DIRECTORY if item_path.is_dir() \
             else None
 
+        file_size = 0 if file_type is FileType.DIRECTORY else os_stat.st_size
+
         return FileStat(
+            file_name=file_name,
             file_type=file_type,
-            size=os_stat.st_size,
-            ctime=dt.datetime.fromtimestamp(os_stat.st_ctime, dt.timezone.utc),
+            storage_path=str(item_path.relative_to(self._root_path).as_posix()),
+            size=file_size,
             mtime=dt.datetime.fromtimestamp(os_stat.st_mtime, dt.timezone.utc),
-            atime=dt.datetime.fromtimestamp(os_stat.st_atime, dt.timezone.utc),
-            uid=os_stat.st_uid,
-            gid=os_stat.st_gid,
-            mode=os_stat.st_mode)
+            atime=dt.datetime.fromtimestamp(os_stat.st_atime, dt.timezone.utc))
 
-    def ls(self, storage_path: str) -> tp.List[str]:
+    def ls(self, storage_path: str, recursive: bool = False) -> tp.List[FileStat]:
 
         operation = f"LS [{storage_path}]"
-        return self._error_handling(operation, lambda: self._ls(storage_path))
+        return self._error_handling(operation, lambda: self._ls(storage_path, recursive))
 
-    def _ls(self, storage_path: str) -> tp.List[str]:
+    def _ls(self, storage_path: str, recursive: bool = False) -> tp.List[FileStat]:
 
-        item_path = self._root_path / storage_path
-        return [str(x.relative_to(item_path))
-                for x in item_path.iterdir()
-                if x.is_file() or x.is_dir()]
+        item_path = self._resolve_path(storage_path, "LS", True)
 
-    def mkdir(self, storage_path: str, recursive: bool = False, exists_ok: bool = False):
+        if not item_path.exists():
+            raise ex.EStorageRequest(f"Storage path does not exist: LS [{storage_path}]")
+
+        # If LS is called on anything other than a directory, return a listing of that one item
+        if not item_path.is_dir():
+            os_stat = item_path.stat()
+            stat = self._os_to_trac_stat(item_path, os_stat)
+            return [stat]
+
+        # Otherwise do a regular directory listing
+        else:
+            pattern = "**/*" if recursive else "*"
+            paths = list(item_path.glob(pattern))
+            return list(map(lambda p: self._os_to_trac_stat(p, p.stat()), paths))
+
+    def mkdir(self, storage_path: str, recursive: bool = False):
 
         operation = f"MKDIR [{storage_path}]"
-        self._error_handling(operation, lambda: self._mkdir(storage_path, recursive, exists_ok))
+        self._error_handling(operation, lambda: self._mkdir(storage_path, recursive))
 
-    def _mkdir(self, storage_path: str, recursive: bool = False, exists_ok: bool = False):
+    def _mkdir(self, storage_path: str, recursive: bool = False):
 
-        item_path = self._root_path / storage_path
-        item_path.mkdir(parents=recursive, exist_ok=exists_ok)
+        item_path = self._resolve_path(storage_path, "MKDIR", False)
+        item_path.mkdir(parents=recursive, exist_ok=True)
 
-    def rm(self, storage_path: str, recursive: bool = False):
+    def rm(self, storage_path: str):
 
-        operation = f"MKDIR [{storage_path}]"
-        self._error_handling(operation, lambda: self._rm(storage_path, recursive))
+        operation = f"RM [{storage_path}]"
+        self._error_handling(operation, lambda: self._rm(storage_path))
+
+    def _rm(self, storage_path: str):
+
+        item_path = self._resolve_path(storage_path, "RM", False)
+
+        if not item_path.is_file():
+            raise ex.EStorageRequest(f"Storage path is not a file: RM [{storage_path}]")
+
+        item_path.unlink()
+
+    def rmdir(self, storage_path: str):
+
+        operation = f"RMDIR [{storage_path}]"
+        self._error_handling(operation, lambda: self._rmdir(storage_path))
 
-    def _rm(self, storage_path: str, recursive: bool = False):
+    def _rmdir(self, storage_path: str):
 
-        raise NotImplementedError()
+        item_path = self._resolve_path(storage_path, "RMDIR", False)
 
-    def read_bytes(self, storage_path: str) -> bytes:
+        if not item_path.is_dir():
+            raise ex.EStorageRequest(f"Storage path is not a directory: RMDIR [{storage_path}]")
 
-        operation = f"READ BYTES [{storage_path}]"
-        return self._error_handling(operation, lambda: self._read_bytes(storage_path))
+        self._rmdir_inner(item_path)
 
-    def _read_bytes(self, storage_path: str) -> bytes:
+    def _rmdir_inner(self, item_path):
 
-        with self.read_byte_stream(storage_path) as stream:
-            return stream.read()
+        for item in item_path.iterdir():
+            if item.is_dir():
+                self._rmdir_inner(item)
+            else:
+                item.unlink()
+
+        item_path.rmdir()
 
     def read_byte_stream(self, storage_path: str) -> tp.BinaryIO:
 
@@ -154,90 +282,97 @@ class LocalFileStorage(IFileStorage):
 
     def _read_byte_stream(self, storage_path: str) -> tp.BinaryIO:
 
-        operation = f"CLOSE BYTE STREAM (READ) [{storage_path}]"
-        item_path = self._root_path / storage_path
-        stream = open(item_path, mode='rb')
+        item_path = self._resolve_path(storage_path, "OPEN BYTE STREAM (READ)", False)
 
-        return _helpers.log_close(stream, self._log, operation)
+        # Do not try to open directories or other non-file objects for reading
+        if item_path.exists() and not item_path.is_file():
+            raise ex.EStorageRequest(f"Storage path is not a file: OPEN BYTE STREAM (READ) [{storage_path}]")
 
-    def write_bytes(self, storage_path: str, data: bytes, overwrite: bool = False):
+        stream = open(item_path, mode='rb')
 
-        operation = f"WRITE BYTES [{storage_path}]"
-        self._error_handling(operation, lambda: self._write_bytes(storage_path, data, overwrite))
+        return _StreamResource(stream, lambda: self._close_byte_stream(storage_path, stream))
 
-    def _write_bytes(self, storage_path: str, data: bytes, overwrite: bool = False):
+    def write_byte_stream(self, storage_path: str) -> tp.BinaryIO:
 
-        with self.write_byte_stream(storage_path, overwrite) as stream:
-            stream.write(data)
+        operation = f"OPEN BYTE STREAM (WRITE) [{storage_path}]"
+        return self._error_handling(operation, lambda: self._write_byte_stream(storage_path))
 
-    def write_byte_stream(self, storage_path: str, overwrite: bool = False) -> tp.BinaryIO:
+    def _write_byte_stream(self, storage_path: str) -> tp.BinaryIO:
 
-        operation = f"OPEN BYTE STREAM (WRITE) [{storage_path}]"
-        return self._error_handling(operation, lambda: self._write_byte_stream(storage_path, overwrite))
+        item_path = self._resolve_path(storage_path, "OPEN BYTE STREAM (WRITE)", False)
 
-    def _write_byte_stream(self, storage_path: str, overwrite: bool = False) -> tp.BinaryIO:
+        # Make sure the parent dir always exists
+        # This brings local storage in line with cloud bucket semantics for writing objects
+        if not item_path.parent.exists():
+            item_path.parent.mkdir(parents=True, exist_ok=True)
 
-        operation = f"CLOSE BYTE STREAM (WRITE) [{storage_path}]"
-        item_path = self._root_path / storage_path
+        # Do not try to open directories or other non-file objects for write
+        if item_path.exists() and not item_path.is_file():
+            raise ex.EStorageRequest(f"Storage path is not a file: OPEN BYTE STREAM (WRITE) [{storage_path}]")
 
-        if overwrite:
-            stream = open(item_path, mode='wb')
-        else:
-            stream = open(item_path, mode='xb')
+        # If the file does not already exist and there is an error, try to clean it up
+        delete_on_error = not item_path.exists()
 
-        return _helpers.log_close(stream, self._log, operation)
+        # Always overwrite existing files, this is in line with cloud bucket semantics
+        stream = open(item_path, mode='wb')
 
-    def read_text(self, storage_path: str, encoding: str = 'utf-8') -> str:
+        return _StreamResource(stream, lambda: self._close_byte_stream(storage_path, stream, delete_on_error))
 
-        operation = f"READ TEXT [{storage_path}]"
-        return self._error_handling(operation, lambda: self._read_text(storage_path, encoding))
+    def _close_byte_stream(self, storage_path: str, stream: tp.BinaryIO, delete_on_error: bool = False):
 
-    def _read_text(self, storage_path: str, encoding: str = 'utf-8') -> str:
+        if stream.closed:
+            return
 
-        with self.read_text_stream(storage_path, encoding) as stream:
-            return stream.read()
+        try:
+            read_write = "WRITE" if stream.writable() else "READ"
+            self._log.info(f"CLOSE BYTE STREAM ({read_write}) [{storage_path}]")
 
-    def read_text_stream(self, storage_path: str, encoding: str = 'utf-8') -> tp.TextIO:
+        finally:
+            stream.close()
 
-        operation = f"OPEN TEXT STREAM (READ) [{storage_path}]"
-        return self._error_handling(operation, lambda: self._read_text_stream(storage_path, encoding))
+        exc_info = sys.exc_info()
+        error = exc_info[1] if exc_info is not None else None
 
-    def _read_text_stream(self, storage_path: str, encoding: str = 'utf-8') -> tp.TextIO:
+        if error is not None and delete_on_error:
+            try:
+                item_path = self._resolve_path(storage_path, "CLOSE BYTE STREAM (WRITE)", False)
+                if item_path.exists():
+                    item_path.unlink()
+            except OSError:
+                pass
 
-        operation = f"CLOSE TEXT STREAM (READ) [{storage_path}]"
-        item_path = self._root_path / storage_path
-        stream = open(item_path, mode='rt', encoding=encoding)
+    __T = tp.TypeVar("__T")
 
-        return _helpers.log_close(stream, self._log, operation)
+    def _resolve_path(self, storage_path: str, operation_name: str, allow_root_dir: bool) -> pathlib.Path:
 
-    def write_text(self, storage_path: str, data: str, encoding: str = 'utf-8', overwrite: bool = False):
+        try:
 
-        operation = f"WRITE TEXT [{storage_path}]"
-        self._error_handling(operation, lambda: self._write_text(storage_path, data, encoding, overwrite))
+            if storage_path is None or len(storage_path.strip()) == 0:
+                raise ex.EStorageValidation(f"Storage path is null or blank: {operation_name} [{storage_path}]")
 
-    def _write_text(self, storage_path: str, data: str, encoding: str = 'utf-8', overwrite: bool = False):
+            if self._ILLEGAL_PATH_CHARS.match(storage_path):
+                raise ex.EStorageValidation(f"Storage path is invalid: {operation_name} [{storage_path}]")
 
-        with self.write_text_stream(storage_path, encoding, overwrite) as stream:
-            stream.write(data)
+            relative_path = pathlib.Path(storage_path)
 
-    def write_text_stream(self, storage_path: str, encoding: str = 'utf-8', overwrite: bool = False) -> tp.TextIO:
+            if relative_path.is_absolute():
+                raise ex.EStorageValidation(f"Storage path is not relative: {operation_name} [{storage_path}]")
 
-        operation = f"OPEN TEXT STREAM (WRITE) [{storage_path}]"
-        return self._error_handling(operation, lambda: self._write_text_stream(storage_path, encoding, overwrite))
+            root_path = self._root_path
+            absolute_path = self._root_path.joinpath(relative_path).resolve(False)
 
-    def _write_text_stream(self, storage_path: str, encoding: str = 'utf-8', overwrite: bool = False) -> tp.TextIO:
+            # is_relative_to only supported in Python 3.9+, we need to support 3.7
+            if absolute_path != root_path and root_path not in absolute_path.parents:
+                raise ex.EStorageValidation(f"Path is outside storage root: {operation_name} [{storage_path}]")
 
-        operation = f"CLOSE TEXT STREAM (WRITE) [{storage_path}]"
-        item_path = self._root_path / storage_path
+            if absolute_path == root_path and not allow_root_dir:
+                raise ex.EStorageValidation(f"Illegal operation for storage root: {operation_name} [{storage_path}]")
 
-        if overwrite:
-            stream = open(item_path, mode='wt', encoding=encoding)
-        else:
-            stream = open(item_path, mode='xt', encoding=encoding)
+            return absolute_path
 
-        return _helpers.log_close(stream, self._log, operation)
+        except ValueError as e:
 
-    __T = tp.TypeVar("__T")
+            raise ex.EStorageValidation(f"Storage path is invalid: {operation_name} [{storage_path}]") from e
 
     def _error_handling(self, operation: str, func: tp.Callable[[], __T]) -> __T:
 
@@ -245,6 +380,11 @@ class LocalFileStorage(IFileStorage):
             self._log.info(operation)
             return func()
 
+        # ETrac means the error is already handled, log the message as-is
+        except ex.ETrac as e:
+            self._log.exception(f"{operation} {str(e)}")
+            raise
+
         except FileNotFoundError as e:
             msg = "File not found"
             self._log.exception(f"{operation}: {msg}")
@@ -255,6 +395,16 @@ class LocalFileStorage(IFileStorage):
             self._log.exception(f"{operation}: {msg}")
             raise ex.EStorageRequest(msg) from e
 
+        except IsADirectoryError as e:
+            msg = "Path is a directory, not a file"
+            self._log.exception(f"{operation}: {msg}")
+            raise ex.EStorageRequest(msg) from e
+
+        except NotADirectoryError as e:
+            msg = "Path is not a directory"
+            self._log.exception(f"{operation}: {msg}")
+            raise ex.EStorageRequest(msg) from e
+
         except PermissionError as e:
             msg = "Access denied"
             self._log.exception(f"{operation}: {msg}")
@@ -265,5 +415,6 @@ class LocalFileStorage(IFileStorage):
             self._log.exception(f"{operation}: {msg}")
             raise ex.EStorageAccess(msg) from e
 
-
-_storage.StorageManager.register_storage_type("LOCAL", LocalFileStorage, _storage.CommonDataStorage)
+    _ILLEGAL_PATH_CHARS_WINDOWS = re.compile(r".*[\x00<>:\"\'|?*].*")
+    _ILLEGAL_PATH_CHARS_POSIX = re.compile(r".*[\x00<>:\"\'|?*\\].*")
+    _ILLEGAL_PATH_CHARS = _ILLEGAL_PATH_CHARS_WINDOWS if _helpers.is_windows() else _ILLEGAL_PATH_CHARS_POSIX