spin-sdk 3.2.0__tar.gz → 3.3.0__tar.gz

{spin_sdk-3.2.0/src/spin_sdk.egg-info → spin_sdk-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spin-sdk
-Version: 3.2.0
+Version: 3.3.0
 Summary: Experimental SDK for Spin and Componentize-Py
 Author-email: Fermyon Engineering <engineering@fermyon.com>
 Maintainer-email: Fermyon Engineering <engineering@fermyon.com>
@@ -254,7 +254,7 @@ enter a virtual environment and then install the desired packages
 ```shell
 python -m venv .venv
 source .venv/bin/activate
-pip install componentize-py==0.13.3 spin-sdk==3.1.0 mypy==1.8.0
+pip install componentize-py==0.16.0 spin-sdk==3.3.0 mypy==1.8.0
 ```
 
 ### Hello, World

{spin_sdk-3.2.0 → spin_sdk-3.3.0}/README.md

@@ -24,7 +24,7 @@ enter a virtual environment and then install the desired packages
 ```shell
 python -m venv .venv
 source .venv/bin/activate
-pip install componentize-py==0.13.3 spin-sdk==3.1.0 mypy==1.8.0
+pip install componentize-py==0.16.0 spin-sdk==3.3.0 mypy==1.8.0
 ```
 
 ### Hello, World

{spin_sdk-3.2.0 → spin_sdk-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spin-sdk"
-version = "3.2.0"
+version = "3.3.0"
 description = "Experimental SDK for Spin and Componentize-Py"
 readme = "README.md"
 license = { file = "LICENSE" }

spin_sdk-3.3.0/src/spin_sdk/componentize-py.toml

@@ -0,0 +1,5 @@
+wit_directory = "wit"
+bindings = "wit"
+
+[import_interface_names]
+"fermyon:spin/postgres@2.0.0" = "postgres"

spin_sdk-3.3.0/src/spin_sdk/http/__init__.py

@@ -0,0 +1,236 @@
+"""Module with helpers for wasi http"""
+
+import asyncio
+import traceback
+from spin_sdk.http import poll_loop
+from spin_sdk.http.poll_loop import PollLoop, Sink, Stream
+from spin_sdk.wit.types import Ok, Err
+from spin_sdk.wit.imports.types import (
+    IncomingResponse, Method, Method_Get, Method_Head, Method_Post, Method_Put, Method_Delete, Method_Connect, Method_Options,
+    Method_Trace, Method_Patch, Method_Other, IncomingRequest, IncomingBody, ResponseOutparam, OutgoingResponse,
+    Fields, Scheme, Scheme_Http, Scheme_Https, Scheme_Other, OutgoingRequest, OutgoingBody
+)
+from spin_sdk.wit.imports.streams import StreamError_Closed
+from dataclasses import dataclass
+from collections.abc import MutableMapping
+from typing import Optional
+from urllib import parse
+
+@dataclass
+class Request:
+    """An HTTP request"""
+    method: str
+    uri: str
+    headers: MutableMapping[str, str]
+    body: Optional[bytes]
+
+@dataclass
+class Response:
+    """An HTTP response"""
+    status: int
+    headers: MutableMapping[str, str]
+    body: Optional[bytes]
+
+try:
+    from spin_sdk.wit import exports
+    from spin_sdk.wit.exports import IncomingHandler as Base
+    
+    class IncomingHandler(Base):
+        """Simplified handler for incoming HTTP requests using blocking, buffered I/O."""
+
+        def handle_request(self, request: Request) -> Response:
+            """Handle an incoming HTTP request and return a response or raise an error"""
+            raise NotImplementedError
+
+        def handle(self, request: IncomingRequest, response_out: ResponseOutparam):
+            method = request.method()
+
+            if isinstance(method, Method_Get):
+                method_str = "GET"
+            elif isinstance(method, Method_Head):
+                method_str = "HEAD"
+            elif isinstance(method, Method_Post):
+                method_str = "POST"
+            elif isinstance(method, Method_Put):
+                method_str = "PUT"
+            elif isinstance(method, Method_Delete):
+                method_str = "DELETE"
+            elif isinstance(method, Method_Connect):
+                method_str = "CONNECT"
+            elif isinstance(method, Method_Options):
+                method_str = "OPTIONS"
+            elif isinstance(method, Method_Trace):
+                method_str = "TRACE"
+            elif isinstance(method, Method_Patch):
+                method_str = "PATCH"
+            elif isinstance(method, Method_Other):
+                method_str = method.value
+            else:
+                raise AssertionError
+
+            request_body = request.consume()
+            request_stream = request_body.stream()
+            body = bytearray()
+            while True:
+                try:
+                    body += request_stream.blocking_read(16 * 1024)
+                except Err as e:
+                    if isinstance(e.value, StreamError_Closed):
+                        request_stream.__exit__(None, None, None)
+                        IncomingBody.finish(request_body)
+                        break
+                    else:
+                        raise e
+
+            request_uri = request.path_with_query()
+            if request_uri is None:
+                uri = "/"
+            else:
+                uri = request_uri
+    
+            try:
+                simple_response = self.handle_request(Request(
+                    method_str,
+                    uri,
+                    dict(map(lambda pair: (pair[0], str(pair[1], "utf-8")), request.headers().entries())),
+                    bytes(body)
+                ))
+            except:
+                traceback.print_exc()
+    
+                response = OutgoingResponse(Fields())
+                response.set_status_code(500)
+                ResponseOutparam.set(response_out, Ok(response))
+                return
+
+            if simple_response.headers.get('content-length') is None:
+                content_length = len(simple_response.body) if simple_response.body is not None else 0
+                simple_response.headers['content-length'] = str(content_length)
+
+            response = OutgoingResponse(Fields.from_list(list(map(
+                lambda pair: (pair[0], bytes(pair[1], "utf-8")),
+                simple_response.headers.items()
+            ))))
+            response_body = response.body()
+            response.set_status_code(simple_response.status)
+            ResponseOutparam.set(response_out, Ok(response))
+            response_stream = response_body.write()
+            if simple_response.body is not None:
+                MAX_BLOCKING_WRITE_SIZE = 4096
+                offset = 0
+                while offset < len(simple_response.body):
+                    count = min(len(simple_response.body) - offset, MAX_BLOCKING_WRITE_SIZE)
+                    response_stream.blocking_write_and_flush(simple_response.body[offset:offset+count])
+                    offset += count
+            response_stream.__exit__(None, None, None)
+            OutgoingBody.finish(response_body, None)
+
+except ImportError:
+    # `spin_sdk.wit.exports` won't exist if the use is targeting `spin-imports`,
+    # so just skip this part
+    pass
+
+def send(request: Request) -> Response:
+    """Send an HTTP request and return a response or raise an error"""
+    loop = PollLoop()
+    asyncio.set_event_loop(loop)
+    return loop.run_until_complete(send_async(request))
+    
+
+async def send_async(request: Request) -> Response:
+    match request.method:
+        case "GET":
+            method: Method = Method_Get()
+        case "HEAD":
+            method = Method_Head()
+        case "POST":
+            method = Method_Post()
+        case "PUT":
+            method = Method_Put()
+        case "DELETE":
+            method = Method_Delete()
+        case "CONNECT":
+            method = Method_Connect()
+        case "OPTIONS":
+            method = Method_Options()
+        case "TRACE":
+            method = Method_Trace()
+        case "PATCH":
+            method = Method_Patch()
+        case _:
+            method = Method_Other(request.method)
+    
+    url_parsed = parse.urlparse(request.uri)
+
+    match url_parsed.scheme:
+            case "http":
+                scheme: Scheme = Scheme_Http()
+            case "https":
+                scheme = Scheme_Https()
+            case "":
+                scheme = Scheme_Http()
+            case _:
+                scheme = Scheme_Other(url_parsed.scheme)
+
+    headers_dict = request.headers
+
+    # Add a `content-length` header if the caller didn't include one, but did
+    # specify a body:
+    if headers_dict.get('content-length') is None:
+        content_length = len(request.body) if request.body is not None else 0
+        # Make a copy rather than mutate in place, since the caller might not
+        # expect us to mutate it:
+        headers_dict = headers_dict.copy()
+        headers_dict['content-length'] = str(content_length)
+
+    headers = list(map(
+        lambda pair: (pair[0], bytes(pair[1], "utf-8")),
+        headers_dict.items()
+    ))
+
+    outgoing_request = OutgoingRequest(Fields.from_list(headers))
+    outgoing_request.set_method(method)
+    outgoing_request.set_scheme(scheme)
+    if url_parsed.netloc == '':
+        if scheme == "http":
+            authority = ":80"
+        else:
+            authority = ":443"
+    else:
+        authority = url_parsed.netloc
+
+    outgoing_request.set_authority(authority)
+
+    path_and_query = url_parsed.path
+    if url_parsed.query:
+        path_and_query += '?' + url_parsed.query
+    outgoing_request.set_path_with_query(path_and_query)
+
+    outgoing_body = request.body if request.body is not None else bytearray()
+    sink = Sink(outgoing_request.body())
+    incoming_response: IncomingResponse = (await asyncio.gather(
+        poll_loop.send(outgoing_request),
+        send_and_close(sink, outgoing_body)
+    ))[0]
+
+    response_body = Stream(incoming_response.consume())
+    body = bytearray()
+    while True:
+        chunk = await response_body.next()
+        if chunk is None:
+            simple_response = Response(
+                incoming_response.status(),
+                dict(map(
+                    lambda pair: (pair[0], str(pair[1], "utf-8")),
+                    incoming_response.headers().entries()
+                )),
+                bytes(body)
+            )
+            incoming_response.__exit__(None, None, None)
+            return simple_response
+        else:
+            body += chunk
+
+async def send_and_close(sink: Sink, data: bytes):
+    await sink.send(data)
+    sink.close()

{spin_sdk-3.2.0 → spin_sdk-3.3.0}/src/spin_sdk/http/poll_loop.py

@@ -31,7 +31,7 @@ async def send(request: OutgoingRequest) -> IncomingResponse:
         if response is None:
             await register(cast(PollLoop, asyncio.get_event_loop()), future.subscribe())
         else:
-            future.__exit__()
+            future.__exit__(None, None, None)
             
             if isinstance(response, Ok):
                 if isinstance(response.value, Ok):
@@ -65,7 +65,7 @@ class Stream:
             except Err as e:
                 if isinstance(e.value, StreamError_Closed):
                     if self.stream is not None:
-                        self.stream.__exit__()
+                        self.stream.__exit__(None, None, None)
                         self.stream = None
                     if self.body is not None:
                         IncomingBody.finish(self.body)
@@ -104,7 +104,7 @@ class Sink:
     def close(self):
         """Close the stream, indicating no further data will be written."""
 
-        self.stream.__exit__()
+        self.stream.__exit__(None, None, None)
         self.stream = None
         OutgoingBody.finish(self.body, None)
         self.body = None
@@ -143,7 +143,7 @@ class PollLoop(asyncio.AbstractEventLoop):
                 
                 for (ready, pollable), waker in zip(zip(ready, pollables), wakers):
                     if ready:
-                        pollable.__exit__()
+                        pollable.__exit__(None, None, None)
                         waker.set_result(None)
                     else:
                         new_wakers.append((pollable, waker))

{spin_sdk-3.2.0 → spin_sdk-3.3.0}/src/spin_sdk/wit/__init__.py

@@ -1,6 +1,7 @@
 """ Module with the bindings generated from the wit by componentize-py """
 
 from typing import TypeVar, Generic, Union, Optional, Protocol, Tuple, List, Any, Self
+from types import TracebackType
 from enum import Flag, Enum, auto
 from dataclasses import dataclass
 from abc import abstractmethod

spin_sdk-3.3.0/src/spin_sdk/wit/deps/keyvalue-2024-10-17/atomic.wit

@@ -0,0 +1,46 @@
+/// A keyvalue interface that provides atomic operations.
+/// 
+/// Atomic operations are single, indivisible operations. When a fault causes an atomic operation to
+/// fail, it will appear to the invoker of the atomic operation that the action either completed
+/// successfully or did nothing at all.
+/// 
+/// Please note that this interface is bare functions that take a reference to a bucket. This is to
+/// get around the current lack of a way to "extend" a resource with additional methods inside of
+/// wit. Future version of the interface will instead extend these methods on the base `bucket`
+/// resource.
+interface atomics {
+  use store.{bucket, error};
+
+  /// The error returned by a CAS operation
+  variant cas-error {
+	/// A store error occurred when performing the operation
+	store-error(error),
+	  /// The CAS operation failed because the value was too old. This returns a new CAS handle
+	  /// for easy retries. Implementors MUST return a CAS handle that has been updated to the
+	  /// latest version or transaction.
+	cas-failed(cas),
+  }
+
+  /// A handle to a CAS (compare-and-swap) operation.
+  resource cas {
+	/// Construct a new CAS operation. Implementors can map the underlying functionality
+	/// (transactions, versions, etc) as desired.
+	new: static func(bucket: borrow<bucket>, key: string) -> result<cas, error>;
+	/// Get the current value of the key (if it exists). This allows for avoiding reads if all
+	/// that is needed to ensure the atomicity of the operation
+	current: func() -> result<option<list<u8>>, error>;
+  }
+
+  /// Atomically increment the value associated with the key in the store by the given delta. It
+  /// returns the new value.
+  ///
+  /// If the key does not exist in the store, it creates a new key-value pair with the value set
+  /// to the given delta.
+  ///
+  /// If any other error occurs, it returns an `Err(error)`.
+  increment: func(bucket: borrow<bucket>, key: string, delta: s64) -> result<s64, error>;
+
+  /// Perform the swap on a CAS operation. This consumes the CAS handle and returns an error if
+  /// the CAS operation failed.
+  swap: func(cas: cas, value: list<u8>) -> result<_, cas-error>;
+}

spin_sdk-3.3.0/src/spin_sdk/wit/deps/keyvalue-2024-10-17/batch.wit

@@ -0,0 +1,63 @@
+/// A keyvalue interface that provides batch operations.
+/// 
+/// A batch operation is an operation that operates on multiple keys at once.
+/// 
+/// Batch operations are useful for reducing network round-trip time. For example, if you want to
+/// get the values associated with 100 keys, you can either do 100 get operations or you can do 1
+/// batch get operation. The batch operation is faster because it only needs to make 1 network call
+/// instead of 100.
+/// 
+/// A batch operation does not guarantee atomicity, meaning that if the batch operation fails, some
+/// of the keys may have been modified and some may not. 
+/// 
+/// This interface does has the same consistency guarantees as the `store` interface, meaning that
+/// you should be able to "read your writes."
+/// 
+/// Please note that this interface is bare functions that take a reference to a bucket. This is to
+/// get around the current lack of a way to "extend" a resource with additional methods inside of
+/// wit. Future version of the interface will instead extend these methods on the base `bucket`
+/// resource.
+interface batch {
+  use store.{bucket, error};
+
+  /// Get the key-value pairs associated with the keys in the store. It returns a list of
+  /// key-value pairs.
+  ///
+  /// If any of the keys do not exist in the store, it returns a `none` value for that pair in the
+  /// list.
+  ///
+  /// MAY show an out-of-date value if there are concurrent writes to the store.
+  ///
+  /// If any other error occurs, it returns an `Err(error)`.
+  get-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<list<tuple<string, option<list<u8>>>>, error>;
+
+  /// Set the values associated with the keys in the store. If the key already exists in the
+  /// store, it overwrites the value.
+  ///
+  /// Note that the key-value pairs are not guaranteed to be set in the order they are provided.
+  ///
+  /// If any of the keys do not exist in the store, it creates a new key-value pair.
+  ///
+  /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not
+  /// rollback the key-value pairs that were already set. Thus, this batch operation does not
+  /// guarantee atomicity, implying that some key-value pairs could be set while others might
+  /// fail.
+  ///
+  /// Other concurrent operations may also be able to see the partial results.
+  set-many: func(bucket: borrow<bucket>, key-values: list<tuple<string, list<u8>>>) -> result<_, error>;
+
+  /// Delete the key-value pairs associated with the keys in the store.
+  ///
+  /// Note that the key-value pairs are not guaranteed to be deleted in the order they are
+  /// provided.
+  ///
+  /// If any of the keys do not exist in the store, it skips the key.
+  ///
+  /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not
+  /// rollback the key-value pairs that were already deleted. Thus, this batch operation does not
+  /// guarantee atomicity, implying that some key-value pairs could be deleted while others might
+  /// fail.
+  ///
+  /// Other concurrent operations may also be able to see the partial results.
+  delete-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<_, error>;
+}

spin_sdk-3.3.0/src/spin_sdk/wit/deps/keyvalue-2024-10-17/store.wit

@@ -0,0 +1,122 @@
+/// A keyvalue interface that provides eventually consistent key-value operations.
+/// 
+/// Each of these operations acts on a single key-value pair.
+/// 
+/// The value in the key-value pair is defined as a `u8` byte array and the intention is that it is
+/// the common denominator for all data types defined by different key-value stores to handle data,
+/// ensuring compatibility between different key-value stores. Note: the clients will be expecting
+/// serialization/deserialization overhead to be handled by the key-value store. The value could be
+/// a serialized object from JSON, HTML or vendor-specific data types like AWS S3 objects.
+/// 
+/// Data consistency in a key value store refers to the guarantee that once a write operation
+/// completes, all subsequent read operations will return the value that was written.
+/// 
+/// Any implementation of this interface must have enough consistency to guarantee "reading your
+/// writes." In particular, this means that the client should never get a value that is older than
+/// the one it wrote, but it MAY get a newer value if one was written around the same time. These
+/// guarantees only apply to the same client (which will likely be provided by the host or an
+/// external capability of some kind). In this context a "client" is referring to the caller or
+/// guest that is consuming this interface. Once a write request is committed by a specific client,
+/// all subsequent read requests by the same client will reflect that write or any subsequent
+/// writes. Another client running in a different context may or may not immediately see the result
+/// due to the replication lag. As an example of all of this, if a value at a given key is A, and
+/// the client writes B, then immediately reads, it should get B. If something else writes C in
+/// quick succession, then the client may get C. However, a client running in a separate context may
+/// still see A or B
+interface store {
+  /// The set of errors which may be raised by functions in this package
+  variant error {
+    /// The host does not recognize the store identifier requested.
+    no-such-store,
+
+      /// The requesting component does not have access to the specified store
+      /// (which may or may not exist).
+    access-denied,
+
+      /// Some implementation-specific error has occurred (e.g. I/O)
+    other(string)
+  }
+
+  /// A response to a `list-keys` operation.
+  record key-response {
+    /// The list of keys returned by the query.
+    keys: list<string>,
+      /// The continuation token to use to fetch the next page of keys. If this is `null`, then
+      /// there are no more keys to fetch.
+    cursor: option<string>
+  }
+
+  /// Get the bucket with the specified identifier.
+  ///
+  /// `identifier` must refer to a bucket provided by the host.
+  ///
+  /// `error::no-such-store` will be raised if the `identifier` is not recognized.
+  open: func(identifier: string) -> result<bucket, error>;
+
+  /// A bucket is a collection of key-value pairs. Each key-value pair is stored as a entry in the
+  /// bucket, and the bucket itself acts as a collection of all these entries.
+  ///
+  /// It is worth noting that the exact terminology for bucket in key-value stores can very
+  /// depending on the specific implementation. For example:
+  ///
+  /// 1. Amazon DynamoDB calls a collection of key-value pairs a table
+  /// 2. Redis has hashes, sets, and sorted sets as different types of collections
+  /// 3. Cassandra calls a collection of key-value pairs a column family
+  /// 4. MongoDB calls a collection of key-value pairs a collection
+  /// 5. Riak calls a collection of key-value pairs a bucket
+  /// 6. Memcached calls a collection of key-value pairs a slab
+  /// 7. Azure Cosmos DB calls a collection of key-value pairs a container
+  ///
+  /// In this interface, we use the term `bucket` to refer to a collection of key-value pairs
+  resource bucket {
+    /// Get the value associated with the specified `key`
+    ///
+    /// The value is returned as an option. If the key-value pair exists in the
+    /// store, it returns `Ok(value)`. If the key does not exist in the
+    /// store, it returns `Ok(none)`.
+    ///
+    /// If any other error occurs, it returns an `Err(error)`.
+    get: func(key: string) -> result<option<list<u8>>, error>;
+
+    /// Set the value associated with the key in the store. If the key already
+    /// exists in the store, it overwrites the value.
+    ///
+    /// If the key does not exist in the store, it creates a new key-value pair.
+    ///
+    /// If any other error occurs, it returns an `Err(error)`.
+    set: func(key: string, value: list<u8>) -> result<_, error>;
+
+    /// Delete the key-value pair associated with the key in the store.
+    ///
+    /// If the key does not exist in the store, it does nothing.
+    ///
+    /// If any other error occurs, it returns an `Err(error)`.
+    delete: func(key: string) -> result<_, error>;
+
+    /// Check if the key exists in the store.
+    ///
+    /// If the key exists in the store, it returns `Ok(true)`. If the key does
+    /// not exist in the store, it returns `Ok(false)`.
+    ///
+    /// If any other error occurs, it returns an `Err(error)`.
+    exists: func(key: string) -> result<bool, error>;
+
+    /// Get all the keys in the store with an optional cursor (for use in pagination). It
+    /// returns a list of keys. Please note that for most KeyValue implementations, this is a
+    /// can be a very expensive operation and so it should be used judiciously. Implementations
+    /// can return any number of keys in a single response, but they should never attempt to
+    /// send more data than is reasonable (i.e. on a small edge device, this may only be a few
+    /// KB, while on a large machine this could be several MB). Any response should also return
+    /// a cursor that can be used to fetch the next page of keys. See the `key-response` record
+    /// for more information.
+    ///
+    /// Note that the keys are not guaranteed to be returned in any particular order.
+    ///
+    /// If the store is empty, it returns an empty list.
+    ///
+    /// MAY show an out-of-date list of keys if there are concurrent writes to the store.
+    ///
+    /// If any error occurs, it returns an `Err(error)`.
+    list-keys: func(cursor: option<string>) -> result<key-response, error>;
+  }
+}

spin_sdk-3.3.0/src/spin_sdk/wit/deps/keyvalue-2024-10-17/watch.wit

@@ -0,0 +1,16 @@
+/// A keyvalue interface that provides watch operations.
+/// 
+/// This interface is used to provide event-driven mechanisms to handle
+/// keyvalue changes.
+interface watcher {
+  /// A keyvalue interface that provides handle-watch operations.
+  use store.{bucket};
+
+  /// Handle the `set` event for the given bucket and key. It includes a reference to the `bucket`
+  /// that can be used to interact with the store.
+  on-set: func(bucket: bucket, key: string, value: list<u8>);
+
+  /// Handle the `delete` event for the given bucket and key. It includes a reference to the
+  /// `bucket` that can be used to interact with the store.
+  on-delete: func(bucket: bucket, key: string);
+}

spin_sdk-3.3.0/src/spin_sdk/wit/deps/keyvalue-2024-10-17/world.wit

@@ -0,0 +1,26 @@
+package wasi: keyvalue@0.2.0-draft2;
+
+/// The `wasi:keyvalue/imports` world provides common APIs for interacting with key-value stores.
+/// Components targeting this world will be able to do:
+/// 
+/// 1. CRUD (create, read, update, delete) operations on key-value stores.
+/// 2. Atomic `increment` and CAS (compare-and-swap) operations.
+/// 3. Batch operations that can reduce the number of round trips to the network.
+world imports {
+  /// The `store` capability allows the component to perform eventually consistent operations on
+  /// the key-value store.
+  import store;
+
+  /// The `atomic` capability allows the component to perform atomic / `increment` and CAS
+  /// (compare-and-swap) operations.
+  import atomics;
+
+  /// The `batch` capability allows the component to perform eventually consistent batch
+  /// operations that can reduce the number of round trips to the network.
+  import batch;
+}
+
+world watch-service {
+  include imports;
+  export watcher;
+}