fabric-chaincode-python 2.5.2__py3-none-any.whl

src/fabric_shim/handler.py

@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: Apache-2.0
+import datetime
+from typing import AsyncIterable
+import asyncio
+import grpc
+
+from fabric_protos.peer import chaincode_shim_pb2 as ccshim_pb2
+from fabric_protos.peer import chaincode_pb2 as cc_pb2
+from fabric_protos.peer import proposal_response_pb2 as pr_pb
+from src.fabric_shim.stub import ChaincodeStub
+from src.fabric_shim.msg_queue_handler import MsgQueueHandler, QueueMessage
+from src.fabric_shim.response import new_error_msg, ResponseCode
+from src.fabric_shim.utils import generate_logging_prefix
+from src.fabric_shim.logging import LOGGER
+from src.fabric_shim.interfaces import Chaincode
+
+
+class STATES:
+    CREATED = "created"  # start state
+    ESTABLISHED = "established"  # connection established
+    READY = "ready"  # ready for requests
+
+
+MIN_UNICODE_RUNE_VALUE = '\u0000'  # U + 0000
+MAX_UNICODE_RUNE_VALUE = '\u0010FFFF'  # U+10FFFF - maximum (and unallocated) code point
+COMPOSITEKEY_NS = '\x00'
+EMPTY_KEY_SUBSTITUTE = '\x01'
+
+class Handler:
+    def __init__(self, cc_id: str, cc: Chaincode) -> None:
+        self.chaincode_id = cc_pb2.ChaincodeID()
+        self.chaincode_id.name = cc_id
+        self.chaincode = cc
+        self.msg_queue_handler = None
+        self.context = None
+        self.state = STATES.CREATED
+        self._pending_tasks = set()
+
+    def _track_task(self, coro):
+        """Schedule message handling while surfacing task failures in logs."""
+        task = asyncio.create_task(coro)
+        self._pending_tasks.add(task)
+
+        def _done_callback(done_task):
+            self._pending_tasks.discard(done_task)
+            try:
+                exc = done_task.exception()
+            except asyncio.CancelledError:
+                return
+            if exc is not None:
+                LOGGER.exception('Unhandled exception while processing peer message', exc_info=exc)
+
+        task.add_done_callback(_done_callback)
+
+    async def handle_stub_interaction(self, msg, action="Invoke"):
+        """handle_message calls the Init | Invoke function of the associated chaincode."""
+        # Get the function and args from Payload
+        cc_input = cc_pb2.ChaincodeInput()
+        cc_input.ParseFromString(msg.payload)
+        
+        stub = ChaincodeStub(self, msg.channel_id, msg.txid, cc_input, msg.proposal)
+
+        # Normalize action and call appropriate chaincode method
+        action_normalized = (action or "").lower()
+        if action_normalized == 'init':
+            method = 'Init'
+            resp: pr_pb.Response = await self.chaincode.init(stub)
+        else:
+            method = 'Invoke'
+            resp: pr_pb.Response = await self.chaincode.invoke(stub)
+
+        # check that a response object has been returned otherwise assume an error.
+
+        if not resp or not resp.status:
+            err_msg = '%s Calling chaincode %s() has not called success or error.' \
+                      % (generate_logging_prefix(msg.channel_id, msg.txid), method)
+            LOGGER.info(err_msg)
+
+            resp = pr_pb.Response(
+                status=ResponseCode.ERROR,
+                message=err_msg
+            )
+
+        LOGGER.info('%s Calling chaincode %s(), response status: %s'
+                    % (generate_logging_prefix(msg.channel_id, msg.txid), method, resp.status))
+
+        if resp.status >= ResponseCode.ERROR:
+            err_msg = '%s Calling chaincode %s() returned error response [%s]. Sending COMPLETED message back to peer' \
+                      % (generate_logging_prefix(msg.channel_id, msg.txid), method, resp.message)
+            LOGGER.info(err_msg)
+
+            next_state_msg = ccshim_pb2.ChaincodeMessage(
+                type=ccshim_pb2.ChaincodeMessage.COMPLETED,
+                payload=resp.SerializeToString(),
+                txid=msg.txid,
+                channel_id=msg.channel_id
+            )
+        else:
+            LOGGER.info('%s Calling chaincode %s() succeeded. Sending COMPLETED message back to peer'
+                        % (generate_logging_prefix(msg.channel_id, msg.txid), method))
+
+            next_state_msg = ccshim_pb2.ChaincodeMessage(
+                type=ccshim_pb2.ChaincodeMessage.COMPLETED,
+                payload=resp.SerializeToString(),
+                txid=msg.txid,
+                channel_id=msg.channel_id
+            )
+
+        await self.context.write(next_state_msg)
+
+    async def handle_message_ready(self, msg):
+        """handle_message_ready handles messages received from the peer when the handler is in the "ready" state."""
+        if msg.type == ccshim_pb2.ChaincodeMessage.RESPONSE or msg.type == ccshim_pb2.ChaincodeMessage.ERROR:
+            LOGGER.info("+++ ERROR or RESPONSE +++")
+            await self.msg_queue_handler.handle_msg_response(msg)
+        elif msg.type == ccshim_pb2.ChaincodeMessage.INIT:
+            LOGGER.info("+++ call INIT +++")
+            await self.handle_stub_interaction(msg, "Init")
+            return
+        elif msg.type == ccshim_pb2.ChaincodeMessage.TRANSACTION:
+            LOGGER.info("+++ call INVOKE +++")
+            await self.handle_stub_interaction(msg, "Invoke")
+            return
+        else:
+            await self.context.write(new_error_msg(msg, self.state))
+
+    async def handle_message_established(self, msg):
+        """
+        handle_message_established handles messages received from the peer when the handler is in the "established" state.
+        """
+        if msg.type != ccshim_pb2.ChaincodeMessage.READY:
+            LOGGER.error(f'Chaincode is in "established" state, can only process messages of type "ready", '
+                         f'but received "{msg.type}"')
+            await self.context.write(new_error_msg(msg, self.state))
+        else:
+            LOGGER.info('Successfully established communication with peer node. State transferred to "ready"')
+            self.state = STATES.READY
+
+    async def handle_message_created(self, msg):
+        """handle_message_created handles messages received from the peer when the handler is in the "created" state."""
+        if msg.type != ccshim_pb2.ChaincodeMessage.REGISTERED:
+            LOGGER.error(f'Chaincode is in "created" state, can only process messages of type "registered", '
+                         f'but received "{msg.type}"')
+            await self.context.write(new_error_msg(msg, self.state))
+        else:
+            LOGGER.info('Successfully registered with peer node. State transferred to "established"')
+            self.state = STATES.ESTABLISHED
+
+    async def handle_message(self, msg: ccshim_pb2.ChaincodeMessage):
+        """handle_message message handles loop for shim side of chaincode/peer stream."""
+        LOGGER.warning('-->> Look out!')
+
+        # TODO: ?
+        if msg.type == ccshim_pb2.ChaincodeMessage.KEEPALIVE:
+            LOGGER.info('-| KEEPALIVE')
+            return
+
+        if self.state == STATES.READY:
+            await self.handle_message_ready(msg)
+        elif self.state == STATES.ESTABLISHED:
+            await self.handle_message_established(msg)
+        elif self.state == STATES.CREATED:
+            await self.handle_message_created(msg)
+        else:
+            await self.context.write(new_error_msg(msg, self.state))
+
+    async def chat_with_peer(self, stream: AsyncIterable[ccshim_pb2.ChaincodeMessage], context: grpc.aio.ServicerContext):
+        """chat stream for peer-chaincode interactions post connection"""
+        self.state = STATES.CREATED
+
+        self.context = context
+        self.msg_queue_handler = MsgQueueHandler(self)
+
+        # Send the ChaincodeID during register.
+        cm = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.REGISTER, payload=self.chaincode_id.SerializeToString())
+        cm.timestamp.FromDatetime(datetime.datetime.now())
+
+        # Register on the stream
+        await self.context.write(cm)
+
+        async for receive_message in stream:
+            LOGGER.info('Received message')
+            if receive_message is None:
+                err_str = "received nil message, ending chaincode stream"
+                LOGGER.error(err_str)
+                return ccshim_pb2.ChaincodeMessage(
+                    type=ccshim_pb2.ChaincodeMessage.ERROR, payload=err_str.encode(encoding='utf-8'))
+            else:
+                # Keep handling asynchronous so the stream can continue receiving
+                # response frames needed by in-flight request futures.
+                self._track_task(self.handle_message(receive_message))
+
+                LOGGER.info(f'->>>>  proposal  {receive_message.proposal}')
+                LOGGER.info(f'->>>>  payload  {receive_message.payload}')
+                LOGGER.info(f'->>>>  channel ID  {receive_message.channel_id}')
+                LOGGER.info(f'->>>>  Tx ID  {receive_message.txid}')
+
+        if self._pending_tasks:
+            await asyncio.gather(*self._pending_tasks, return_exceptions=True)
+
+    async def handle_get_state(self, collection, key, channel_id, tx_id):
+        msg_pb = ccshim_pb2.GetState()
+        msg_pb.key = key
+        msg_pb.collection = collection
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.GET_STATE,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id
+        )
+
+        result = await self.__ask_peer_and_listen(msg, 'GetState')
+        return result.payload
+    
+    async def handle_put_state(self, collection, key, value, channel_id, tx_id):
+        msg_pb = ccshim_pb2.PutState()
+        msg_pb.key = key
+        msg_pb.value = value
+        msg_pb.collection = collection
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.PUT_STATE,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id
+        )
+        return await self.__ask_peer_and_listen(msg, 'PutState')
+
+    async def handle_delete_state(self, collection, key, channel_id, tx_id):
+        msg_pb = ccshim_pb2.DelState()
+        msg_pb.key = key
+        msg_pb.collection = collection
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.DEL_STATE,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id
+        )
+        return await self.__ask_peer_and_listen(msg, 'DeleteState')
+
+    async def handle_get_state_by_range(self, collection, start_key, end_key,
+                                          channel_id, tx_id, metadata=None):
+        """Send a GetStateByRange request to the peer.
+
+        ``metadata`` (if present) is a serialised :class:`QueryMetadata`
+        message — used for pagination.
+        """
+        msg_pb = ccshim_pb2.GetStateByRange()
+        # NB: the protobuf field names are camelCase (startKey/endKey), not
+        # snake_case.
+        msg_pb.startKey = start_key or ""
+        msg_pb.endKey = end_key or ""
+        msg_pb.collection = collection
+        if metadata is not None:
+            msg_pb.metadata = metadata
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.GET_STATE_BY_RANGE,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'GetStateByRange')
+
+    async def handle_get_query_result(self, collection, query, channel_id, tx_id,
+                                       metadata=None):
+        """Send a GetQueryResult (CouchDB rich query) request to the peer."""
+        msg_pb = ccshim_pb2.GetQueryResult()
+        msg_pb.query = query
+        msg_pb.collection = collection
+        if metadata is not None:
+            msg_pb.metadata = metadata
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.GET_QUERY_RESULT,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'GetQueryResult')
+
+    async def handle_get_history_for_key(self, key, channel_id, tx_id):
+        """Send a GetHistoryForKey request to the peer."""
+        msg_pb = ccshim_pb2.GetHistoryForKey()
+        msg_pb.key = key
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.GET_HISTORY_FOR_KEY,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'GetHistoryForKey')
+
+    async def handle_query_state_next(self, query_id, channel_id, tx_id):
+        """Fetch the next page of an in-flight paged query."""
+        msg_pb = ccshim_pb2.QueryStateNext()
+        msg_pb.id = query_id
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.QUERY_STATE_NEXT,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'QueryStateNext')
+
+    async def handle_query_state_close(self, query_id, channel_id, tx_id):
+        """Close an in-flight paged query."""
+        msg_pb = ccshim_pb2.QueryStateClose()
+        msg_pb.id = query_id
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.QUERY_STATE_CLOSE,
+            payload=msg_pb.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'QueryStateClose')
+
+    async def handle_invoke_chaincode(self, chaincode_name, args, channel_id, tx_id):
+        """Invoke another chaincode by name."""
+        ci = cc_pb2.ChaincodeInput()
+        for a in args:
+            ci.args.append(a.encode() if isinstance(a, str) else a)
+        msg = ccshim_pb2.ChaincodeMessage(
+            type=ccshim_pb2.ChaincodeMessage.INVOKE_CHAINCODE,
+            payload=ci.SerializeToString(),
+            txid=tx_id,
+            channel_id=channel_id,
+        )
+        return await self.__ask_peer_and_listen(msg, 'InvokeChaincode')
+
+    async def __ask_peer_and_listen(self, msg, action):
+        loop = asyncio.get_running_loop()
+        fut = loop.create_future()
+
+        message = QueueMessage(msg, action, fut)
+        await self.msg_queue_handler.queue_msg(message)
+
+        return await fut

src/fabric_shim/interfaces.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+from abc import ABC, abstractmethod
+
+from fabric_protos.peer import proposal_response_pb2 as pb
+
+
+class ChaincodeStubInterface(ABC):
+    """
+    ChaincodeStubInterface is used by deployable chaincode apps to access and modify their ledgers
+    """
+    def get_function_and_parameters(self):  # Get the chaincode calling method name and parameter list
+        pass
+
+    def get_txid(self):  # Get the ID of the chaincode calling transaction
+        pass
+
+    def get_channel_id(self):  # Get the channel ID of the chaincode calling transaction
+        pass
+
+    def get_creator(self):  # Get the user ID of the chaincode calling transaction
+        pass
+
+    def get_transient(self):  # Get the transient dataset of chaincode call transactions
+        pass
+
+    def get_tx_timestamp(self):  # Get the timestamp of the chaincode calling transaction
+        pass
+
+    @abstractmethod
+    def get_state(self, key: str): #-> bytearray:
+        """
+            GetState returns the value of the specified `key` from the
+            ledger. Note that GetState doesn't read data from the writeset, which
+            has not been committed to the ledger. In other words, GetState doesn't
+            consider data modified by PutState that has not been committed.
+            If the key does not exist in the state database, (nil, nil) is returned.
+        """
+
+    def put_state(self, key: str, value):  # update the state of the specified key on the ledger
+        pass
+
+    def delete_state(self, key: str):  # delete the state of the specified key on the ledger
+        pass
+
+    def set_state_validation_parameter(self):  # Set state validation parameters
+        pass
+
+    def get_state_validation_parameter(self):  # Get state validation parameters
+        pass
+
+    def get_state_by_range(self):  # Get the state of the keys in the specified range on the ledger
+        pass
+
+    def get_state_by_range_with_pagination(
+            self):  # Pagination to get the state of the keys in the specified range on the ledger
+        pass
+
+    def get_query_result(self):  # Get the node rich query result, which is only valid when couchdb is used
+        pass
+
+    def get_query_result_with_pagination(self):  # Pagination to get node rich query results
+        pass
+
+    def get_history_for_key(self):  # Get the update history of the specified key on the ledger
+        pass
+
+    def invoke_chaincode(self):  # Invoke other chaincodes
+        pass
+
+    def set_event(self):  # trigger chaincode event
+        pass
+
+    def create_composite_key(self):  # Create a composite key
+        pass
+
+    # split composite key, return composite key type and composition attribute value
+    def split_composite_key(self):
+        pass
+
+    def get_state_by_partial_composite_key(self):  # Query the ledger state using a partial composite key
+        pass
+
+    # Use partial composite key pagination to query ledger state
+    def get_state_by_partial_composite_key_with_pagination(self):
+        pass
+
+    def get_private_data(self):  # Get the status of the specified key in the specified private dataset
+        pass
+
+    def get_private_data_hash(self):  # Get the state hash of the specified key in the specified private dataset
+        pass
+
+    def put_private_data(self):  # Update the state of the specified key in the specified private dataset
+        pass
+
+    def delete_private_data(self):  # delete the specified key in the specified private data set
+        pass
+
+    def set_private_data_validation_parameter(self):  # Set validation parameters for private data
+        pass
+
+    def get_private_data_validation_parameter(self):  # Get the validation parameters for private data
+        pass
+
+    # Get the status of the keys of the specified range in the specified private dataset
+    def get_private_data_by_range(self):
+        pass
+
+    def get_private_data_by_partial_composite_key(self):  # Query a private dataset with a partial composite key
+        pass
+
+    # Get rich query results for private datasets, only valid when couchdb is enabled
+    def get_private_data_query_result(self):
+        pass
+
+
+class Chaincode(ABC):
+    @staticmethod
+    @abstractmethod
+    async def init(stub: ChaincodeStubInterface) -> pb.Response:
+        """
+        init is called during Instantiate transaction after the chaincode container has been established for the
+        first time, allowing the chaincode to initialize its internal data
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    async def invoke(stub: ChaincodeStubInterface) -> pb.Response:
+        """
+        invoke is called to update or query the ledger in a proposal transaction. Updated state variables are not
+        committed to the ledger until the transaction is committed.
+        """
+        pass

src/fabric_shim/iterators.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Asynchronous iterators for Fabric state / history / query results.
+
+The contract API exposes three operations that return iterators over ledger
+data:
+
+* :func:`ChaincodeStub.get_state_by_range` / :func:`get_state_by_partial_composite_key`
+  → :class:`StateQueryIterator`
+* :func:`ChaincodeStub.get_query_result` (CouchDB rich queries)
+  → :class:`QueryResultIterator` (same wire protocol as state queries)
+* :func:`ChaincodeStub.get_history_for_key`
+  → :class:`HistoryQueryIterator` (yields :class:`KeyModification` records)
+
+Each iterator transparently pages through the peer's responses by sending
+``QueryStateNext`` messages until the peer reports ``has_more == false``,
+then closes the query with ``QueryStateClose`` when the iteration ends.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator, List, Optional
+
+
+class _QueryIteratorBase:
+    """Common base for paged query iterators."""
+
+    def __init__(self, handler, channel_id: str, tx_id: str,
+                 initial_response, response_factory, parser):
+        self._handler = handler
+        self._channel_id = channel_id
+        self._tx_id = tx_id
+        self._response_factory = response_factory  # callable(msg_bytes) -> QueryResponse
+        self._parser = parser  # callable(QueryResultBytes) -> parsed value
+        self._buffer: List[Any] = []
+        self._id: Optional[str] = None
+        self._has_more: bool = False
+        self._closed: bool = False
+        self._consume(initial_response)
+
+    def _consume(self, raw_msg) -> None:
+        """Parse a peer QueryResponse message into buffer + pagination state."""
+        if raw_msg is None:
+            return
+        resp = self._response_factory(raw_msg.payload)
+        self._id = resp.id
+        for qrb in resp.results:
+            self._buffer.append(self._parser(qrb))
+        self._has_more = bool(resp.has_more)
+
+    async def __aiter__(self):
+        return self
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if self._buffer:
+            return self._buffer.pop(0)
+        if not self._has_more or self._id is None:
+            await self._close()
+            raise StopAsyncIteration
+        # Request the next page from the peer.
+        next_response = await self._handler.handle_query_state_next(
+            self._id, self._channel_id, self._tx_id,
+        )
+        self._consume(next_response)
+        if self._buffer:
+            return self._buffer.pop(0)
+        await self._close()
+        raise StopAsyncIteration
+
+    async def _close(self) -> None:
+        if self._closed or self._id is None:
+            self._closed = True
+            return
+        self._closed = True
+        try:
+            await self._handler.handle_query_state_close(
+                self._id, self._channel_id, self._tx_id,
+            )
+        except Exception:
+            # Best-effort close; iterators must not raise on close.
+            pass
+
+    async def aclose(self) -> None:
+        """Explicit close — safe to call multiple times."""
+        await self._close()
+
+
+class StateQueryIterator(_QueryIteratorBase):
+    """Iterates over (key, value) byte pairs returned by GetStateByRange."""
+
+
+class QueryResultIterator(_QueryIteratorBase):
+    """Iterates over rich-query (CouchDB) results."""
+
+
+class HistoryQueryIterator(_QueryIteratorBase):
+    """Iterates over :class:`KeyModification` records returned by GetHistoryForKey."""
+
+
+__all__ = [
+    "StateQueryIterator",
+    "QueryResultIterator",
+    "HistoryQueryIterator",
+]

src/fabric_shim/logger.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

src/fabric_shim/logging.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+import asyncio
+import logging
+import logging.handlers
+
+try:
+    # Python 3.7 and newer, fast reentrant implementation
+    # without task tracking (not needed for that when logging)
+    from queue import SimpleQueue as Queue
+except ImportError:
+    from queue import Queue
+from typing import List
+
+LOGGER = logging.getLogger("asyncio")
+
+
+class LocalQueueHandler(logging.handlers.QueueHandler):
+    """
+    Network logging can block the event loop. It is recommended to use a separate thread for handling logs or use
+    non-blocking IO.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        # Removed the call to self.prepare(), handle task cancellation
+        try:
+            self.enqueue(record)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            self.handleError(record)
+
+
+def setup_logging_queue() -> List[logging.Handler]:
+    """Move log handlers to a separate thread.
+
+    Replace handlers on the root logger with a LocalQueueHandler,
+    and start a logging.QueueListener holding the original
+    handlers.
+
+    """
+    queue = Queue()
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s %(message)s')
+
+    handlers: List[logging.Handler] = []
+
+    handler = LocalQueueHandler(queue)
+    LOGGER.addHandler(handler)
+    for h in LOGGER.handlers[:]:
+        if h is not handler:
+            LOGGER.removeHandler(h)
+            handlers.append(h)
+
+    listener = logging.handlers.QueueListener(
+        queue, *handlers, respect_handler_level=True
+    )
+    # Keep a global reference to the listener so it is not garbage collected
+    global _QUEUE_LISTENER
+    _QUEUE_LISTENER = listener
+    listener.start()
+
+
+setup_logging_queue()
+# logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s %(message)s')