@toa.io/extensions.exposition 1.0.0-alpha.86 → 1.0.0-alpha.88

package/documentation/octets.md

@@ -14,7 +14,7 @@ directives under the current RTD Node.
   octets:context: images
 ```
 
-## `octets:store`
+## `octets:put`
 
 Stores the content of the request body into a storage, under the request path with
 specified `content-type`.
@@ -35,7 +35,7 @@ The value of the directive is `null` or an object with the following properties:
 /images:
   octets:context: images
   POST:
-    octets:store:
+    octets:put:
       accept:
         - image/jpeg
         - image/png
@@ -45,7 +45,7 @@ The value of the directive is `null` or an object with the following properties:
         analyze: images.analyze
 ```
 
-Non-standard `content-meta` header can be used
+Non-standard `content-attributes` header can be used
 to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
 
 The value of the `content-meta` header is a comma-separated list of key-value string pairs.
@@ -54,18 +54,18 @@ If no value is provided for a key, the string `true` is used.
 ```http
 POST /images/ HTTP/1.1
 content-type: image/jpeg
-content-meta: foo, bar=baz
-content-meta: baz=1
+content-attributes: foo, bar=baz
+content-attributes: baz=1
 ```
 
 ```yaml
-meta:
+attributes:
   foo: 'true'
   bar: 'baz'
   baz: '1'
 ```
 
-If the Entry already exists, the `content-meta` header is ignored.
+If the Entry already exists, the `content-attributes` header is ignored.
 
 ### Stream size limit
 
@@ -86,7 +86,7 @@ The default value is `64MiB`.
 
 ### Downloading external content
 
-The `octets:store` directive can be used to download external content:
+The `octets:put` directive can be used to download external content:
 
 ```http
 POST /images/ HTTP/1.1
@@ -106,7 +106,7 @@ the [Entry](/extensions/storages/readme.md#entry).
 /images:
   octets:context: images
   POST:
-    octets:store:
+    octets:put:
       trust:
         - https://example.com
         - ^https://example\.com/[a-z]+\.jpe?g$
@@ -114,7 +114,7 @@ the [Entry](/extensions/storages/readme.md#entry).
 
 ### Response
 
-The response of the `octets:store` directive is the created Entry.
+The response of the `octets:put` directive is the created Entry.
 
 ```
 201 Created
@@ -125,7 +125,7 @@ type: image/jpeg
 created: 1698004822358
 ```
 
-If the `octets:store` directive contains a `workflow`, the response
+If the `octets:put` directive contains a `workflow`, the response
 is [multipart](protocol.md#multipart-types).
 The first part represents the created Entry, which is sent immediately after the BLOB is stored,
 while subsequent parts are results from the workflow endpoints, sent as soon as they are available.
@@ -165,7 +165,7 @@ status: exception
 --cut--
 ```
 
-## `octets:fetch`
+## `octets:get`
 
 Fetches the content of a stored BLOB corresponding to the request path, and returns it as the
 response body with the corresponding `content-type`, `content-length`
@@ -177,22 +177,18 @@ The value of the directive is an object with the following properties:
 
 - `meta`: `boolean` indicating whether an Entry is accessible.
   Defaults to `false`.
-- `blob`: `boolean` indicating whether the original BLOB is accessible,
-  [BLOB variant](/extensions/storages/readme.md#async-fetchpath-string-maybereadable) must be
-  specified in the path otherwise.
-  Defaults to `true`.
 
 ```yaml
 /images:
   octets:context: images
   /*:
     GET:
-      octets:fetch:
+      octets:get:
         blob: false # prevent access to the original BLOB
         meta: true  # allow access to an Entry
 ```
 
-The `octets:fetch: ~` declaration is equivalent to defaults.
+The `octets:get: ~` declaration is equivalent to defaults.
 
 To access an Entry, the `accept` request header must contain the `octets.entry` subtype
 in
@@ -203,32 +199,6 @@ GET /images/eecd837c HTTP/1.1
 accept: application/vnd.toa.octets.entry+yaml
 ```
 
-## `octets:list`
-
-Lists the entries stored under the request path.
-
-The value of the directive is an object with the following properties:
-
-- `meta`: `boolean` indicating whether the list of Entries is accessible.
-  Defaults to `false`, which means that only entry identifiers are returned.
-
-```yaml
-/images:
-  octets:context: images
-  GET:
-    octets:list:
-      meta: true
-```
-
-The `octets:list: ~` declaration is equivalent to defaults.
-
-To access a list of Entries, the `accept` request header must contain the `octets.entries` subtype:
-
-```http
-GET /images/ HTTP/1.1
-accept: application/vnd.toa.octets.entries+yaml
-```
-
 ## `octets:delete`
 
 Delete the entry corresponding to the request path.
@@ -288,7 +258,7 @@ as value.
 Steps within a workflow unit are executed in parallel.
 
 ```yaml
-octets:store:
+octets:put:
   workflow:
     resize: images.resize
     analyze: images.analyze
@@ -298,7 +268,7 @@ A workflow can be a single unit, or an array of units.
 If it's an array, the workflow units are executed in sequence.
 
 ```yaml
-octets:store:
+octets:put:
   workflow:
     - optimize: images.optimize   # executed first
     - resize: images.resize       # executed second
@@ -313,7 +283,7 @@ the execution of the workflow is interrupted.
 A workflow unit which value starts with `task:` prefix will be executed as a Task.
 
 ```yaml
-octets:store:
+octets:put:
   workflow:
     optimize: task:images.optimize
 ```

package/features/{octets.meta.feature → octets.attributes.feature}

@@ -1,6 +1,6 @@
-Feature: Octets `content-meta` header
+Feature: Octets `content-attributes` header
 
-  Scenario: Sending `content-meta` header
+  Scenario: Sending `content-attributes` header
     Given the `octets.tester` is running
     And the annotation:
       """yaml
@@ -10,19 +10,19 @@ Feature: Octets `content-meta` header
         octets:context: octets
         /*:
           POST:
-            octets:store: ~
+            octets:put: ~
           /*:
             GET:
-              octets:fetch:
+              octets:get:
                 meta: true
       """
     When the stream of `lenna.ascii` is received with the following headers:
       """
-      POST /meta-header/ HTTP/1.1
+      POST /attributes-header/ HTTP/1.1
       host: nex.toa.io
       content-type: application/octet-stream
-      content-meta: foo, bar=baz=1
-      content-meta: baz=1
+      content-attributes: foo, bar=baz=1
+      content-attributes: baz=1
       """
     Then the following reply is sent:
       """
@@ -30,7 +30,7 @@ Feature: Octets `content-meta` header
       """
     When the following request is received:
       """
-      GET /meta-header/10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
+      GET /attributes-header/10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
       host: nex.toa.io
       accept: application/vnd.toa.octets.entry+yaml
       """
@@ -41,19 +41,20 @@ Feature: Octets `content-meta` header
       id: 10cf16b458f759e0d617f2f3d83599ff
       type: application/octet-stream
       size: 8169
-      meta:
+      checksum: 10cf16b458f759e0d617f2f3d83599ff
+      attributes:
         foo: 'true'
         bar: baz=1
         baz: '1'
       """
 
-  Scenario: CORS allows `content-meta` header
+  Scenario: CORS allows `content-attributes` header
     Given the annotation:
       """yaml
       /:
         octets:context: octets
         POST:
-          octets:store: ~
+          octets:put: ~
       """
     When the following request is received:
       """
@@ -65,5 +66,5 @@ Feature: Octets `content-meta` header
       """
       204 No Content
       access-control-allow-origin: https://example.com
-      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-meta
+      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-attributes
       """

package/features/octets.cloudinary.feature

@@ -0,0 +1,68 @@
+Feature: Octets with Cloudinary storage
+
+  Background:
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        auth:anonymous: true
+        octets:context: cloudinary
+        POST:
+          octets:put: ~
+        /*:
+          GET:
+            octets:get: ~
+          DELETE:
+            octets:delete: ~
+      """
+
+  Scenario: Upload an image
+    When the stream of `lenna.png` is received with the following headers:
+      """
+      POST / HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/octet-stream
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      content-type: application/yaml
+
+      id: 814a0034f5549e957ee61360d87457e5
+      type: image/png
+      size: 473831
+      """
+    When the following request is received:
+      """
+      GET /814a0034f5549e957ee61360d87457e5 HTTP/1.1
+      host: nex.toa.io
+      """
+    Then the stream equals to `lenna.png` is sent with the following headers:
+      """
+      200 OK
+      content-type: image/png
+      content-length: 473831
+      """
+
+  Scenario: Image transformations
+    When the stream of `lenna.png` is received with the following headers:
+      """
+      POST / HTTP/1.1
+      host: nex.toa.io
+      content-type: image/png
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      """
+    When the following request is received:
+      """
+      GET /814a0034f5549e957ee61360d87457e5.48x48.jpeg HTTP/1.1
+      host: nex.toa.io
+      """
+    Then the stream equals to `lenna.48x48.jpeg` is sent with the following headers:
+      """
+      200 OK
+      content-type: image/jpeg
+      """

package/features/octets.download.feature

@@ -1,4 +1,4 @@
-Feature: Download and store
+Feature: Download external resources
 
   Scenario Outline: Download from trusted location defined as <type>
     Given the annotation:
@@ -8,13 +8,13 @@ Feature: Download and store
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store:
+          octets:put:
             trust:
               - <location> # <type>
               - https://github.com
         /*:
           GET:
-            octets:fetch:
+            octets:get:
               meta: true
       """
 
@@ -143,7 +143,7 @@ Feature: Download and store
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store:
+          octets:put:
             limit: 1kb
             trust:
               - https://avatars.githubusercontent.com
@@ -171,7 +171,7 @@ Feature: Download and store
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store:
+          octets:put:
             limit: 1kb
             trust:
               - https://avatars.githubusercontent.com
@@ -185,5 +185,5 @@ Feature: Download and store
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-meta, content-location
+      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-attributes, content-location
       """

package/features/octets.entries.feature

@@ -1,6 +1,6 @@
-Feature: Accessing entries
+Feature: Accessing metadata
 
-  Scenario: Entries are not accessible by default
+  Scenario: Metadata is not accessible by default
     Given the annotation:
       """yaml
       /:
@@ -8,12 +8,10 @@ Feature: Accessing entries
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store: ~
-        GET:
-          octets:list: ~
+          octets:put: ~
         /*:
           GET:
-            octets:fetch: ~
+            octets:get: ~
       """
     When the stream of `lenna.ascii` is received with the following headers:
       """
@@ -25,18 +23,6 @@ Feature: Accessing entries
       """
       201 Created
       """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      host: nex.toa.io
-      accept: application/vnd.toa.octets.entries+yaml
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-
-      Metadata is not accessible.
-      """
     When the following request is received:
       """
       GET /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
@@ -47,10 +33,10 @@ Feature: Accessing entries
       """
       403 Forbidden
 
-      Metadata is not accessible.
+      Metadata is not accessible
       """
 
-  Scenario: Accessing entries
+  Scenario: Accessing metadata
     Given the annotation:
       """yaml
       /:
@@ -58,13 +44,10 @@ Feature: Accessing entries
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store: ~
-        GET:
-          octets:list:
-            meta: true
+          octets:put: ~
         /*:
           GET:
-            octets:fetch:
+            octets:get:
               meta: true
       """
     When the stream of `lenna.ascii` is received with the following headers:
@@ -81,38 +64,6 @@ Feature: Accessing entries
       accept: application/yaml
       content-type: application/octet-stream
       """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      - 10cf16b458f759e0d617f2f3d83599ff
-      - 814a0034f5549e957ee61360d87457e5
-      """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      host: nex.toa.io
-      accept: application/vnd.toa.octets.entries+yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      - id: 10cf16b458f759e0d617f2f3d83599ff
-        size: 8169
-        type: application/octet-stream
-      - id: 814a0034f5549e957ee61360d87457e5
-        size: 473831
-        type: image/png
-      """
     When the following request is received:
       """
       GET /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1

package/features/octets.feature

@@ -8,39 +8,37 @@ Feature: Octets directive family
         auth:anonymous: true
         octets:context: octets
         POST:
-          octets:store: ~
-        GET:
-          octets:list: ~
+          octets:put: ~
         /*:
           GET:
-            octets:fetch: ~
+            octets:get: ~
           DELETE:
             octets:delete: ~
         /media:
           /jpeg:
             POST:
-              octets:store:
+              octets:put:
                 accept: image/jpeg
           /jpeg-or-png:
             POST:
-              octets:store:
+              octets:put:
                 accept:
                   - image/jpeg
                   - image/png
           /images:
             POST:
-              octets:store:
+              octets:put:
                 accept: image/*
             /*:
               GET:
-                octets:fetch: ~
+                octets:get: ~
         /limit-1kb:
           POST:
-            octets:store:
+            octets:put:
               limit: 1kb
         /limit-100kb:
           POST:
-            octets:store:
+            octets:put:
               limit: 100kb
       """
 
@@ -83,19 +81,6 @@ Feature: Octets directive family
       """
       304 Not Modified
       """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      - 10cf16b458f759e0d617f2f3d83599ff
-      """
     When the following request is received:
       """
       GET /10cf16b458f759e0d617f2f3d83599ff?foo=bar HTTP/1.1
@@ -260,40 +245,3 @@ Feature: Octets directive family
 
       Trailing slash is redundant.
       """
-
-  Scenario: Original BLOB is not accessible
-    Given the annotation:
-      """yaml
-      /:
-        io:output: true
-        auth:anonymous: true
-        octets:context: octets
-        POST:
-          octets:store: ~
-        /*:
-          GET:
-            octets:fetch:
-              meta: true
-              blob: false
-      """
-    When the stream of `lenna.ascii` is received with the following headers:
-      """
-      POST / HTTP/1.1
-      host: nex.toa.io
-      """
-    Then the following reply is sent:
-      """
-      201 Created
-      """
-    When the following request is received:
-      """
-      GET /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
-      host: nex.toa.io
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-
-      BLOB variant must be specified.
-      """

package/features/octets.workflows.feature

@@ -13,7 +13,6 @@ Feature: Octets storage workflows
               - add-foo: octets.tester.foo
                 add-bar: octets.tester.bar
               - add-baz: octets.tester.baz
-              - diversify: octets.tester.diversify
         /*:
           io:output: true
           GET:
@@ -51,43 +50,8 @@ Feature: Octets storage workflows
 
       step: add-baz
       status: completed
-      --cut
-
-      step: diversify
-      output: hello
-      status: completed
       --cut--
       """
-    When the following request is received:
-      """
-      GET /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
-      host: nex.toa.io
-      accept: application/vnd.toa.octets.entry+yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      id: 10cf16b458f759e0d617f2f3d83599ff
-      type: application/octet-stream
-      size: 8169
-      meta:
-        foo: bar
-        bar: baz
-        baz: qux
-      """
-    When the following request is received:
-      """
-      GET /10cf16b458f759e0d617f2f3d83599ff.hello.png HTTP/1.1
-      host: nex.toa.io
-      """
-    Then the stream equals to `lenna.png` is sent with the following headers:
-      """
-      200 OK
-      content-type: image/png
-      content-length: 473831
-      """
 
   Scenario: Getting error when running workflow on `store`
     Given the `octets.tester` is running

package/features/steps/.env.example

@@ -0,0 +1,3 @@
+CLOUDINARY_ENVIRONMENT=
+TOA_STORAGES_CLOUDINARY_API_KEY=
+TOA_STORAGES_CLOUDINARY_API_SECRET=

package/features/steps/Parameters.ts

@@ -1,7 +1,11 @@
+import { join } from 'node:path'
+import * as dotenv from 'dotenv'
 import { setDefaultTimeout } from '@cucumber/cucumber'
 import { encode } from '@toa.io/generic'
 import { console } from 'openspan'
 
+dotenv.config({ path: join(__dirname, '.env') })
+
 export class Parameters {
   public readonly origin: string
 
@@ -20,5 +24,11 @@ process.env.TOA_STORAGES = encode({
   octets: {
     provider: 'tmp',
     directory: Math.random().toString(36).substring(2)
+  },
+  cloudinary: {
+    provider: 'cloudinary',
+    environment: process.env.CLOUDINARY_ENVIRONMENT ?? 'nope',
+    type: 'image',
+    prefix: 'toa-dev'
   }
 })

package/features/steps/components/octets.tester/manifest.toa.yaml

@@ -17,7 +17,6 @@ operations:
   err: *operation
   echo: *operation
   concat: *operation
-  diversify: *operation
   yield: *operation
   yex: *operation
   authority: *operation

package/features/steps/components/octets.tester/operations/bar.js

@@ -4,7 +4,6 @@ import { setTimeout } from 'node:timers/promises'
 
 async function bar (input, context) {
   await setTimeout(10)
-  await context.storages.octets.annotate(input.path, 'bar', 'baz')
 
   return { bar: 'baz' }
 }

package/features/steps/components/octets.tester/operations/baz.js

@@ -4,7 +4,6 @@ import { setTimeout } from 'node:timers/promises'
 
 async function baz (input, context) {
   await setTimeout(30)
-  await context.storages.octets.annotate(input.path, 'baz', 'qux')
 }
 
 exports.effect = baz

package/features/steps/components/octets.tester/operations/foo.js

@@ -1,7 +1,6 @@
 'use strict'
 
 async function foo (input, context) {
-  await context.storages.octets.annotate(input.path, 'foo', 'bar')
 }
 
 exports.effect = foo