gala-ki-spielwiese/database/packages/pck_net_storage.pkb

create or replace package body pck_net_storage as

    c_log_module          constant lg_app_log.log_module%type := 'NETZLAUFWERK';

    -- ==================== Private Helpers ====================

    function f_build_url (
         i_object_key in varchar2 default null
        ,i_action     in varchar2 default null
    ) return varchar2
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Baut die vollst<73>ndige OCI Object Storage URL aus den Konfigurationsparametern.
    --                Entweder f<>r eine Bucket-Action, ein einzelnes Objekt oder den Bucket-Root.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Objektschl<68>ssel (Pfad im Bucket); null f<>r Bucket-Root oder Action-URL
    --            i_action      OCI Bucket-Action (z.B. renameObject); null f<>r Objekt-URL
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  Vollst<73>ndige URL als VARCHAR2
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_base  varchar2(1024);
    begin
        l_base := 'https://objectstorage.'
                  || pck_system.f_get_par_wert_by_programmid('NETSTORE_REGION')
                  || '.oraclecloud.com/n/'
                  || pck_system.f_get_par_wert_by_programmid('NETSTORE_NAMESPACE')
                  || '/b/'
                  || pck_system.f_get_par_wert_by_programmid('NETSTORE_BUCKET');

        if i_action is not null
        then
            return l_base || '/actions/' || i_action;
        elsif i_object_key is not null
        then
            -- Sonderzeichen kodieren, Schr<68>gstriche im Key unver<65>ndert lassen
            return l_base || '/o/' || utl_url.escape(i_object_key, false);
        else
            return l_base || '/o';
        end if;
    end f_build_url;

    -- Normalisiert einen Ordnerpfad: stellt sicher, dass er mit / endet.
    -- null bleibt null (= Bucket-Root).
    function f_normalize_prefix (i_prefix in varchar2) return varchar2
    is
    begin
        if i_prefix is null
        then
            return null;
        end if;

        return rtrim(i_prefix, '/') || '/';
    end f_normalize_prefix;

    procedure p_assert_allowed (i_object_key in varchar2)
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Pr<50>ft den Objektschl<68>ssel auf G<>ltigkeit, Path-Traversal-Angriffe und Tenant-Scope.
    --                Wirft Application Error -20008 bei null-Key, -20004 bei Path Traversal,
    --                -20005 bei Scope-Verletzung.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Zu pr<70>fender Objektschl<68>ssel
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    -- SCK  2026-04-10  Null-Pr<50>fung und f<>hrender-Slash-Check erg<72>nzt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_tenant_prefix  varchar2(256);
        l_log_action varchar2(256) := 'ASSERT_ALLOWED';
    begin
        if i_object_key is null
        then
            raise_application_error(-20008, 'Object key darf nicht null sein');
        end if;

        if instr(i_object_key, '..') > 0 or substr(i_object_key, 1, 1) = '/'
        then
            raise_application_error(-20004, 'Path traversal attempt detected');
        end if;

        l_tenant_prefix := pck_system.f_get_par_wert_by_programmid('NETSTORE_TENANT_ID');

        /*
        -- Log for debugging Prefix check
        pck_log.p_info(
             i_module  => c_log_module
            ,i_action  => l_log_action
            ,i_message => 'Checking Prefix: Netstore tenant-Prefix: ' || l_tenant_prefix || '; Accessed Prefix: ' || substr(i_object_key, 1, length(l_tenant_prefix)) || '; Accessed Object: ' || i_object_key
        );
        */

        if l_tenant_prefix is not null and length(l_tenant_prefix) > 0
        then
            if substr(i_object_key, 1, length(l_tenant_prefix)) != l_tenant_prefix
            then
                raise_application_error(-20005, 'Access denied: outside tenant scope');
            end if;
        end if;
    end p_assert_allowed;

    function f_make_request (
         i_method       in varchar2
        ,i_url          in varchar2
        ,i_body_clob    in clob     default null
        ,i_body_blob    in blob     default null
        ,i_content_type in varchar2 default null
    ) return clob
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  F<>hrt einen HTTP-Request gegen die OCI Object Storage API aus.
    --                Wertet den HTTP-Statuscode aus und l<>st bei Fehler einen Application Error aus.
    --                Authentifizierung erfolgt <20>ber APEX Web Credential (NETSTORE_CRED_ID).
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_method       HTTP-Methode (GET, PUT, DELETE, POST, HEAD)
    --            i_url          Vollst<73>ndige Ziel-URL
    --            i_body_clob    Optionaler Request-Body als CLOB (z.B. JSON)
    --            i_body_blob    Optionaler Request-Body als BLOB (Bin<69>rinhalt)
    --            i_content_type Optionaler Content-Type Header
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  Response-Body als CLOB (bei HEAD-Requests leer)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    -- SCK  2026-04-16  empty_blob()/empty_clob() als Default entfernt <20> APEX OCI-Signing braucht null f<>r nicht genutzte Body-Parameter
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_response        clob;
        l_status          number;
        l_header_index    number := 1;
        l_content_length  number;
    begin
        -- headers zur<75>cksetzen - nur zur Sicherheit, damit keine alten Header <20>bertragen werden.
        apex_web_service.g_request_headers.delete;

        if i_content_type is not null
        then
            apex_web_service.g_request_headers(l_header_index).name  := 'Content-Type';
            apex_web_service.g_request_headers(l_header_index).value := i_content_type;
            l_header_index := l_header_index + 1;
        end if;

        /*
        -- Content-Length immer mitsenden (OCI-Signing erfordert es bei PUT/POST,
        -- 0 bei bodylosem Request ist valide)
        if i_body_clob is not null
        then
            l_content_length := coalesce(dbms_lob.getlength(i_body_clob), 0);
            apex_debug.info('clob content length: ' || l_content_length);
        elsif i_body_blob is not null
        then
            l_content_length := coalesce(dbms_lob.getlength(i_body_blob), 0);
            apex_debug.info('blob content length: ' || l_content_length);
        else
            l_content_length := 0;
        end if;

        apex_web_service.g_request_headers(l_header_index).name  := 'Content-Length';
        apex_web_service.g_request_headers(l_header_index).value := l_content_length;
        l_header_index := l_header_index + 1;
        */

        -- nur f<>r leere BLOBs (z.B. leerer Ordner) Content-Length setzen
        -- bei nicht leeren blob setzt apex_web_service.make_rest_request den content-length header automatisch, doppeltes setzen f<>hrt aber zu einem HTTP-400 API Fehler
        -- bei leeren blobs (empty_blob()) wird er aber nicht automatisch gesetzt, daher m<>ssen wir ihn manuell setzen
        if i_body_blob is not null 
            and dbms_lob.getlength(i_body_blob) = 0
        then
            l_content_length := 0; -- coalesce(dbms_lob.getlength(i_body_blob), 0);
            apex_web_service.g_request_headers(l_header_index).name  := 'Content-Length';
            apex_web_service.g_request_headers(l_header_index).value := l_content_length;
            l_header_index := l_header_index + 1;
        end if;

        apex_debug.info('url: ' || i_url);

        if i_body_clob is not null
        then
            --apex_debug.info('Clob Request Body used:');
            --apex_debug.info(i_body_clob);
            l_response := apex_web_service.make_rest_request(
                 p_url                  => i_url
                ,p_http_method          => i_method
                ,p_body                 => i_body_clob
                ,p_credential_static_id => pck_system.f_get_par_wert_by_programmid('NETSTORE_CRED_ID')
                ,p_wallet_path          => pck_system.f_get_par_wert_by_programmid('NETSTORE_WALLET_PATH')
            );
        else
            --apex_debug.info('BLOB Request Body used! Length: ' || dbms_lob.getlength(i_body_blob));
            l_response := apex_web_service.make_rest_request(
                 p_url                  => i_url
                ,p_http_method          => i_method
                ,p_body_blob            => i_body_blob
                ,p_credential_static_id => pck_system.f_get_par_wert_by_programmid('NETSTORE_CRED_ID')
                ,p_wallet_path          => pck_system.f_get_par_wert_by_programmid('NETSTORE_WALLET_PATH')
            );
        end if;

        l_status := apex_web_service.g_status_code;

        if l_status = 404
        then
            raise_application_error(-20001, 'Object not found');
        elsif l_status in (401, 403)
        then
            raise_application_error(-20002, 'OCI authentication failed');
        elsif l_status = 409
        then
            raise_application_error(-20007, 'Object already exists');
        elsif l_status >= 400
        then
            raise_application_error(-20006,
                'OCI API error ' || l_status || ': ' || dbms_lob.substr(l_response, 500, 1));
        end if;

        return l_response;
    end f_make_request;

    -- Interne Implementierung ohne Rechtepr<70>fung <20> wird von f_list_objects und p_delete_folder (Leerpr<70>fung) genutzt
    function f_list_objects_internal (
         i_parent_folder      in varchar2
        ,i_include_subfolders in varchar2
        ,i_start_with         in varchar2
        ,i_limit              in number
    ) return t_net_storage_tab
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Listet Objekte und Unterordner im Bucket ohne Rechte- oder Scope-Pr<50>fung.
    --                Paginiert automatisch <20>ber nextStartWith bis alle Ergebnisse geladen sind.
    --                Wird von f_list_objects (<28>ffentlich) und p_delete_folder (Leerpr<70>fung) intern genutzt.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_parent_folder      Ordnerpfad im Bucket (z.B. eingang/)
    --            i_include_subfolders 'Y' = alle Dateien rekursiv, 'N' = nur direkte Kinder des Ordners
    --            i_start_with         Optionaler Startpunkt f<>r Paginierung
    --            i_limit              Maximale Anzahl Ergebnisse (0 = unbegrenzt)
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  Collection t_net_storage_tab mit allen gefundenen Objekten
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_url           varchar2(4000);
        l_response      clob;
        l_result        t_net_storage_tab := t_net_storage_tab();
        l_next_start    varchar2(1024);
        l_count         number := 0;
        l_done          boolean := false;
        l_cur_start     varchar2(1024) := i_start_with;
        l_parent_folder varchar2(1024) := f_normalize_prefix(i_parent_folder);
        l_obj_path      t_object_path;
        c_page_size     constant number := 1000;
    begin
        while not l_done
        loop
            l_url := f_build_url()
                     || '?limit='  || c_page_size
                     || '&fields=name,size,etag,timeModified'
                     || (case when l_parent_folder      is not null then '&prefix='    || utl_url.escape(l_parent_folder, false) else '' end)
                     || (case when i_include_subfolders = 'N'       then '&delimiter=/'                                          else '' end);

            if l_cur_start is not null
            then
                l_url := l_url || '&start=' || utl_url.escape(l_cur_start, false);
            end if;

            l_response := f_make_request('GET', l_url);

            -- Dateien aus objects-Array einlesen
            for rec in (
                select  jt.object_name
                        ,jt.object_size
                        ,jt.last_modified
                        ,jt.etag
                from    json_table(l_response, '$.objects[*]'
                            columns (
                                 object_name   varchar2(1024) path '$.name'
                                ,object_size   number         path '$.size'
                                ,last_modified varchar2(50)   path '$.timeModified'
                                ,etag          varchar2(256)  path '$.etag'
                            )) jt
            )
            loop
                l_obj_path := f_split_object_key(rec.object_name);
                l_result.extend;
                l_result(l_result.last) := t_net_storage_row(
                     rec.object_name
                    ,l_obj_path.path
                    ,l_obj_path.filename
                    -- Explizit angelegte Ordner sind Zero-Byte-Objekte mit trailing /;
                    -- size, last_modified und etag sind f<>r Ordner nicht relevant
                    ,(case when rec.object_name like '%/' then null else rec.object_size end)
                    ,(case when rec.object_name like '%/' then null else to_date(substr(rec.last_modified, 1, 19), 'YYYY-MM-DD"T"HH24:MI:SS') end)
                    ,(case when rec.object_name like '%/' then 'Y'  else 'N' end)
                    ,(case when rec.object_name like '%/' then null else rec.etag end)
                );
                l_count := l_count + 1;

                if i_limit > 0 and l_count >= i_limit
                then
                    l_done := true;
                    exit;
                end if;
            end loop;

            -- Unterordner aus prefixes-Array einlesen
            if not l_done
            then
                for rec in (
                    select  jt.prefix_name
                    from    json_table(l_response, '$.prefixes[*]'
                                columns (
                                    prefix_name varchar2(1024) path '$'
                                )) jt
                )
                loop
                    l_obj_path := f_split_object_key(rec.prefix_name);
                    l_result.extend;
                    l_result(l_result.last) := t_net_storage_row(
                         rec.prefix_name
                        ,l_obj_path.path
                        ,l_obj_path.filename
                        ,null
                        ,null
                        ,'Y'
                        ,null
                    );
                    l_count := l_count + 1;

                    if i_limit > 0 and l_count >= i_limit
                    then
                        l_done := true;
                        exit;
                    end if;
                end loop;
            end if;

            -- N<>chste Seite pr<70>fen
            if not l_done
            then
                l_next_start := json_value(l_response, '$.nextStartWith');

                if l_next_start is null
                then
                    l_done := true;
                else
                    l_cur_start := l_next_start;
                end if;
            end if;
        end loop;

        -- Implizite Ordner aus Object-Keys ableiten.
        -- Die OCI-API liefert virtuelle Ordner (nie als Zero-Byte-Objekt angelegt) nur
        -- <20>ber $.prefixes, und auch nur wenn delimiter gesetzt ist. Bei rekursivem Abruf
        -- fehlen sie daher komplett. Wir leiten alle Zwischenpfade aus den Object-Keys ab
        -- und erg<72>nzen fehlende Ordner-Eintr<74>ge.
        declare
            l_new_folders  apex_t_varchar2;
        begin
            select  distinct folder_path
            bulk collect into l_new_folders
            from (
                -- Innere Query: alle Zwischenpfade aus den Datei-Keys ableiten.
                --
                -- connect by level iteriert von 1 bis zur Anzahl der Slashes im Key.
                -- instr(..., '/', 1, level) liefert die Position des n-ten Slashes.
                -- substr(..., 1, <position>) schneidet den Key bis einschlie<69>lich
                -- dieses Slashes ab <20> das Ergebnis ist der Ordnerpfad auf Ebene n.
                --
                -- Beispiel f<>r 'mandant/Eingang/batch-001/datei.pdf' (3 Slashes):
                --   level 1 -> 'mandant/'
                --   level 2 -> 'mandant/Eingang/'
                --   level 3 -> 'mandant/Eingang/batch-001/'
                --
                -- prior object_key = object_key  : bindet jede Zeile an sich selbst,
                --   damit connect by die Levels pro Zeile unabh<62>ngig hochz<68>hlt.
                -- prior sys_guid() is not null    : verhindert Cycle-Detection-Fehler,
                --   da keine echte Eltern-Kind-Beziehung vorliegt.
                select  substr(r.object_key, 1, instr(r.object_key, '/', 1, level)) as folder_path
                from    table(l_result) r
                where   r.is_folder = 'N'
                connect by  level      <= regexp_count(r.object_key, '/')
                        and prior r.object_key = r.object_key
                        and prior sys_guid()   is not null
            )
            -- Nur Pfade unterhalb des Parent-Folders behalten:
            -- like-Bedingung schlie<69>t Vorfahren-Pfade aus (z.B. 'mandant/', 'mandant/Eingang/'
            -- wenn der Parent-Folder 'mandant/Eingang/batch/' ist).
            -- != schlie<69>t den Parent-Folder selbst aus.
            -- Bei null-Parent-Folder (Bucket-Root): like '%' = immer wahr, chr(0) passt
            -- auf keinen g<>ltigen Key -> beide Bedingungen greifen nicht.
            where   folder_path like nvl(l_parent_folder, '') || '%'
                and folder_path != nvl(l_parent_folder, chr(0))
            -- Bereits vorhandene Ordner-Eintr<74>ge ausschlie<69>en (explizit angelegte
            -- Zero-Byte-Objekte oder via $.prefixes gelieferte virtuelle Ordner).
            minus
            select  object_key
            from    table(l_result)
            where   is_folder = 'Y';

            for i in 1..l_new_folders.count
            loop
                l_obj_path := f_split_object_key(l_new_folders(i));
                l_result.extend;
                l_result(l_result.last) := t_net_storage_row(
                     l_new_folders(i)
                    ,l_obj_path.path
                    ,l_obj_path.filename
                    ,null
                    ,null
                    ,'Y'
                    ,null
                );
            end loop;
        end;

        return l_result;
    end f_list_objects_internal;

    -- ==================== <20>ffentliche Funktionen ====================

    function f_split_object_key (i_object_key in varchar2) return t_object_path
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Extrahiert Pfad und Dateiname aus einem OCI-Objektschl<68>ssel.
    --                Bei Ordner-Keys (trailing Slash) wird der Ordnername als Dateiname zur<75>ckgegeben.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Vollst<73>ndiger Objektschl<68>ssel (z.B. mandant/Eingang/Import/datei.pdf)
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  t_object_path Record mit path (inkl. trailing Slash) und filename
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-09  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_key     varchar2(1024);
        l_pos     number;
        l_result  t_object_path;
    begin
        -- Trailing Slash entfernen damit Ordner-Keys genauso behandelt werden wie Datei-Keys
        l_key := rtrim(i_object_key, '/');

        l_pos := instr(l_key, '/', -1);

        if l_pos > 0
        then
            l_result.path     := substr(l_key, 1, l_pos);
            l_result.filename := substr(l_key, l_pos + 1);
        else
            l_result.path     := null;
            l_result.filename := l_key;
        end if;

        return l_result;
    end f_split_object_key;

    function f_list_objects (
         i_parent_folder      in varchar2
        ,i_include_subfolders in varchar2 default 'N'
        ,i_start_with         in varchar2 default null
        ,i_limit              in number   default 0
    ) return t_net_storage_tab
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Listet Objekte und Unterordner im Bucket mit Rechtepr<70>fung und Scope-Validierung.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_parent_folder      Ordnerpfad im Bucket (z.B. eingang/)
    --            i_include_subfolders 'Y' = alle Dateien rekursiv inkl. Unterordner, 'N' = nur direkte Dateien im Ordner (Standard)
    --            i_start_with         Optionaler Startpunkt f<>r Paginierung
    --            i_limit              Maximale Anzahl Ergebnisse (0 = unbegrenzt)
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  Collection t_net_storage_tab mit allen gefundenen Objekten
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_parent_folder  varchar2(1024) := f_normalize_prefix(i_parent_folder);
    begin
        pck_mitarbeiterrecht.p_hat_recht('LESEN_ALLES');
        if l_parent_folder is not null
        then
            p_assert_allowed(l_parent_folder);
        end if;
        return f_list_objects_internal(l_parent_folder, i_include_subfolders, i_start_with, i_limit);
    end f_list_objects;

    function f_download_object (i_object_key in varchar2) return blob
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  L<>dt ein einzelnes Objekt aus dem OCI Bucket als BLOB herunter.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Vollst<73>ndiger Objektschl<68>ssel im Bucket
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  Dateiinhalt als BLOB
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_response  blob;
        l_status    number;
    begin
        pck_mitarbeiterrecht.p_hat_recht('LESEN_ALLES');
        p_assert_allowed(i_object_key);

        -- Wir nutzen hier direkt apex_web_service.make_rest_request_b, statt der internen f_make_request funktion, da wir nur hier einen blob statt clob return wert brauchen und eine extra 
        l_response := apex_web_service.make_rest_request_b(
             p_url                  => f_build_url(i_object_key)
            ,p_http_method          => 'GET'
            ,p_credential_static_id => pck_system.f_get_par_wert_by_programmid('NETSTORE_CRED_ID')
            ,p_wallet_path          => pck_system.f_get_par_wert_by_programmid('NETSTORE_WALLET_PATH')
        );


        l_status := apex_web_service.g_status_code;

        if l_status = 404
        then
            raise_application_error(-20001, 'Object not found: ' || i_object_key);
        elsif l_status in (401, 403)
        then
            raise_application_error(-20002, 'OCI authentication failed');
        elsif l_status >= 400
        then
            raise_application_error(-20006, 'OCI API error ' || l_status);
        end if;

        return l_response;
    end f_download_object;

    procedure p_upload_object (
         i_object_key   in varchar2
        ,i_content      in blob
        ,i_content_type in varchar2
    )
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  L<>dt ein Objekt in den OCI Bucket hoch (PUT). <20>berschreibt vorhandene Objekte.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key   Zielpfad im Bucket
    --            i_content      Dateiinhalt als BLOB
    --            i_content_type MIME-Type des Inhalts (z.B. application/octet-stream)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_response  clob;
        l_obj_path  t_object_path;
    begin
        pck_mitarbeiterrecht.p_hat_recht('SCHREIBEN_ALLES');
        p_assert_allowed(i_object_key);

        if substr(i_object_key, -1) = '/'
        then
            raise_application_error(-20012, 'Object Key darf nicht mit / enden <20> zum Anlegen von Ordnern p_create_folder verwenden');
        end if;

        l_response := f_make_request(
             i_method       => 'PUT'
            ,i_url          => f_build_url(i_object_key)
            ,i_body_blob    => i_content
            ,i_content_type => i_content_type
        );

        l_obj_path := f_split_object_key(i_object_key);
        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'UPLOAD'
            ,i_message    => 'Datei "' || l_obj_path.filename || '" hochgeladen  | Ordner: ' || l_obj_path.path
            ,i_object_ref => i_object_key
        );
    end p_upload_object;

    procedure p_delete_object (i_object_key in varchar2)
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  L<>scht ein einzelnes Objekt aus dem OCI Bucket (DELETE).
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Vollst<73>ndiger Objektschl<68>ssel im Bucket
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_response  clob;
        l_obj_path  t_object_path;
    begin
        pck_mitarbeiterrecht.p_hat_recht('ADMIN');
        p_assert_allowed(i_object_key);

        l_response := f_make_request(
             i_method => 'DELETE'
            ,i_url    => f_build_url(i_object_key)
        );

        l_obj_path := f_split_object_key(i_object_key);
        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'DELETE'
            ,i_message    => 'Datei "' || l_obj_path.filename || '" gel<65>scht | Ordner: ' || l_obj_path.path
            ,i_object_ref => i_object_key
        );
    end p_delete_object;

    procedure p_delete_folder (i_folder_key in varchar2)
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  L<>scht einen leeren Ordner im OCI Bucket.
    --                Schl<68>gt fehl, wenn noch Objekte oder Unterordner vorhanden sind.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_folder_key  Kompletter Ordner name inkl. Pfad (z.B. eingang/batch-001/)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    -- SCK  2026-04-10  Rekursives L<>schen entfernt <20> Ordner muss leer sein
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_objects   t_net_storage_tab;
        l_response  clob;
        l_obj_path  t_object_path;
        l_prefix    varchar2(1024) := f_normalize_prefix(i_folder_key);
        l_count     number;
    begin
        pck_mitarbeiterrecht.p_hat_recht('ADMIN');
        p_assert_allowed(l_prefix);

        -- Direkte Kinder pr<70>fen (Dateien und Unterordner)
        l_objects := f_list_objects_internal(
             i_parent_folder      => l_prefix
            ,i_include_subfolders => 'N'
            ,i_start_with         => null
            ,i_limit              => 0
        );

        /*
        apex_debug.info('p_delete_folder: prefix=%s, Anzahl gefundene Eintr<74>ge=%s', l_prefix, l_objects.count);
        for i in 1 .. l_objects.count
        loop
            apex_debug.info('  [%s] key=%s | is_folder=%s', i, l_objects(i).object_key, l_objects(i).is_folder);
        end loop;
        */

        -- Den Ordner selbst (object_key = l_prefix) aus der Z<>hlung ausschlie<69>en
        select  count(*) 
        into    l_count
        from    table(l_objects)
        where   object_key != l_prefix;

        if l_count > 0
        then
            raise_application_error(-20017, 'Ordner ist nicht leer und kann nicht gel<65>scht werden');
        end if;

        -- Ordner-Objekt selbst l<>schen
        l_response := f_make_request(
             i_method => 'DELETE'
            ,i_url    => f_build_url(l_prefix)
        );

        l_obj_path := f_split_object_key(l_prefix);
        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'DELETE_FOLDER'
            ,i_message    => 'Ordner "' || l_obj_path.filename || '" gel<65>scht | Pfad: ' || l_obj_path.path
            ,i_object_ref => l_prefix
        );
    end p_delete_folder;

    procedure p_rename_object (
         i_object_key   in varchar2
        ,i_new_name     in varchar2
    )
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Benennt ein Objekt innerhalb desselben Verzeichnisses um.
    --                Verwendet die OCI renameObject-Action (kein physisches Kopieren).
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Vollst<73>ndiger Objektschl<68>ssel des Quelldatei
    --            i_new_name    Neuer Dateiname (ohne Pfad)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_new_key   varchar2(1024);
        l_body      clob;
        l_response  clob;
        l_obj_path  t_object_path;
    begin
        pck_mitarbeiterrecht.p_hat_recht('SCHREIBEN_ALLES');
        p_assert_allowed(i_object_key);

        if i_new_name is null or length(trim(i_new_name)) = 0
        then
            raise_application_error(-20013, 'Neuer Dateiname darf nicht leer sein');
        end if;

        if instr(i_new_name, '/') > 0
        then
            raise_application_error(-20014, 'Dateiname darf keinen Schr<68>gstrich enthalten <20> zum Verschieben explizite Verschieben-Funktion verwenden');
        end if;

        l_obj_path := f_split_object_key(i_object_key);
        l_new_key  := l_obj_path.path || i_new_name;
        p_assert_allowed(l_new_key);

        if l_new_key = i_object_key
        then
            raise_application_error(-20016, 'Der Dateiname darf beim Umbenennen nicht unver<65>ndert bleiben.');
        end if;

        select  json_object(
                     'sourceName' value i_object_key
                    ,'newName'    value l_new_key
                )
        into    l_body
        from    dual;

        l_response := f_make_request(
             i_method       => 'POST'
            ,i_url          => f_build_url(i_action => 'renameObject')
            ,i_body_clob    => l_body
            ,i_content_type => 'application/json'
        );

        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'RENAME'
            ,i_message    => 'Datei "' || l_obj_path.filename || '" umbenannt in "' || i_new_name || '" | Ordner: ' || l_obj_path.path
            ,i_object_ref => i_object_key
        );
    end p_rename_object;

    procedure p_move_object (
         i_object_key    in varchar2
        ,i_target_prefix in varchar2
    )
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Verschiebt ein Objekt in einen anderen Ordner im selben Bucket.
    --                Verwendet die OCI renameObject-Action (kein physisches Kopieren).
    --                Der Dateiname bleibt erhalten; nur der Pfad <20>ndert sich.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key    Vollst<73>ndiger Objektschl<68>ssel der Quelldatei
    --            i_target_prefix Zielpr<70>fix inkl. trailing Slash (z.B. verarbeitet/batch-001/)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_filename       varchar2(1024);
        l_new_key        varchar2(1024);
        l_body           clob;
        l_response       clob;
        l_obj_path       t_object_path;
        l_target_prefix  varchar2(1024);
    begin
        pck_mitarbeiterrecht.p_hat_recht('SCHREIBEN_ALLES');
        p_assert_allowed(i_object_key);

        if i_target_prefix is null
        then
            raise_application_error(-20015, 'Zielpr<70>fix darf nicht null sein');
        end if;

        l_target_prefix := f_normalize_prefix(i_target_prefix);
        p_assert_allowed(l_target_prefix);

        -- Dateinamen aus dem aktuellen Key extrahieren
        if instr(i_object_key, '/') > 0
        then
            l_filename := substr(i_object_key, instr(i_object_key, '/', -1) + 1);
        else
            l_filename := i_object_key;
        end if;

        l_new_key := l_target_prefix || l_filename;
        p_assert_allowed(l_new_key);

        select  json_object(
                     'sourceName' value i_object_key
                    ,'newName'    value l_new_key
                )
        into    l_body
        from    dual;

        apex_debug.info('Request Body:');
        apex_debug.info(l_body);

        l_response := f_make_request(
             i_method       => 'POST'
            ,i_url          => f_build_url(i_action => 'renameObject')
            ,i_body_clob    => l_body
            ,i_content_type => 'application/json'
        );

        l_obj_path := f_split_object_key(i_object_key);
        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'MOVE'
            ,i_message    => 'Datei "' || l_obj_path.filename || '" verschoben | Von: ' || l_obj_path.path || ' | Nach: ' || l_target_prefix
            ,i_object_ref => i_object_key
        );
    end p_move_object;

    procedure p_create_folder (
         i_parent_folder       in varchar2
        ,i_folder_name  in varchar2
    )
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Legt einen neuen Ordner im OCI Bucket an.
    --                Ordner werden als leeres Objekt mit trailing Slash simuliert.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_parent_folder       <20>bergeordneter Pfad inkl. trailing Slash (z.B. eingang/)
    --            i_folder_name  Name des neuen Ordners (ohne Slash)
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Prozedur erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_folder_key  varchar2(1024);
        l_response    clob;
        l_obj_path    t_object_path;
        l_prefix      varchar2(1024) := f_normalize_prefix(i_parent_folder);
    begin
        pck_mitarbeiterrecht.p_hat_recht('SCHREIBEN_ALLES');

        if i_folder_name is null or length(trim(i_folder_name)) = 0
        then
            raise_application_error(-20010, 'Ordnername darf nicht leer sein');
        end if;

        if instr(i_folder_name, '/') > 0
        then
            raise_application_error(-20011, 'Ordnername darf keinen Schr<68>gstrich enthalten');
        end if;

        if l_prefix is not null
        then
            p_assert_allowed(l_prefix);
        end if;

        -- Ordner als leeres Objekt mit trailing Slash anlegen
        l_folder_key := l_prefix || i_folder_name || '/';
        p_assert_allowed(l_folder_key);

        l_response := f_make_request(
             i_method       => 'PUT'
            ,i_url          => f_build_url(l_folder_key)
            ,i_body_blob    => empty_blob()
            ,i_content_type => 'application/octet-stream'
        );

        l_obj_path := f_split_object_key(l_folder_key);
        pck_log.p_info(
             i_module     => c_log_module
            ,i_action     => 'CREATE_FOLDER'
            ,i_message    => 'Ordner "' || l_obj_path.filename || '" angelegt | Pfad: ' || l_obj_path.path
            ,i_object_ref => l_folder_key
        );
    end p_create_folder;

    function f_get_object_metadata (i_object_key in varchar2) return t_object_meta
    /*Kopf------------------------------------------------------------------------------------------------
    -- Beschreibung:  Ruft die Metadaten eines Objekts per HEAD-Request ab (kein Download des Inhalts).
    --                Liest Gr<47><72>e, Content-Type, Last-Modified und ETag aus den Response-Headern.
    ------------------------------------------------------------------------------------------------------
    -- Parameter: i_object_key  Vollst<73>ndiger Objektschl<68>ssel im Bucket
    ------------------------------------------------------------------------------------------------------
    -- R<>ckgabe:  t_object_meta Record mit object_name, object_size, last_modified, content_type, etag
    ------------------------------------------------------------------------------------------------------
    -- MA   Datum       <20>nderung
    -- SCK  2026-04-08  Funktion erstellt
    ------------------------------------------------------------------------------------------------Kopf*/
    is
        l_response  clob;
        l_result    t_object_meta;
        l_hdr_name  varchar2(256);
    begin
        pck_mitarbeiterrecht.p_hat_recht('LESEN_ALLES');
        p_assert_allowed(i_object_key);

        -- HEAD-Anfrage: leerer Response-Body, Metadaten in Response-Headern
        l_response := f_make_request(
             i_method => 'HEAD'
            ,i_url    => f_build_url(i_object_key)
        );

        l_result.object_name := i_object_key;

        for i in 1..apex_web_service.g_headers.count
        loop
            l_hdr_name := lower(apex_web_service.g_headers(i).name);

            case l_hdr_name
            when 'content-length'
            then
                l_result.object_size := to_number(apex_web_service.g_headers(i).value);
            when 'content-type'
            then
                l_result.content_type := apex_web_service.g_headers(i).value;
            when 'last-modified'
            then
                -- HTTP RFC 7231 Format: "Thu, 01 Jan 2026 00:00:00 GMT"
                l_result.last_modified := to_date(
                     apex_web_service.g_headers(i).value
                    ,'DY, DD MON YYYY HH24:MI:SS "GMT"'
                    ,'NLS_DATE_LANGUAGE=AMERICAN'
                );
            when 'etag'
            then
                l_result.etag := apex_web_service.g_headers(i).value;
            else
                null;
            end case;
        end loop;

        return l_result;
    end f_get_object_metadata;

end pck_net_storage;
/