Merge pull request #348 from kentbull/0-3-0-release

chore: upgrade deps to prep for 0.2.0-rc1 release

.github/workflows/python-app-ci.yml

@@ -20,11 +20,11 @@ jobs:
         os: [ macos-13, ubuntu-latest ]
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.12.2
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12.8
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.12.2
+          python-version: 3.12.8
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -43,11 +43,11 @@ jobs:
   coverage:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.12.2
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12.8
         uses: actions/setup-python@v2
         with:
-          python-version: 3.12.2
+          python-version: 3.12.8
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

Makefile

@@ -1,6 +1,9 @@
 .PHONY: build-keria
 
-VERSION=0.2.0-dev6
+VERSION=0.2.0-rc1
+IMAGE_NAME=weboftrust/keria
+VERSION_TAG=$(IMAGE_NAME):$(VERSION)
+LATEST_TAG=$(IMAGE_NAME):latest
 
 define DOCKER_WARNING
 In order to use the multi-platform build enable the containerd image store
@@ -11,11 +14,21 @@ To enable the feature for Docker Desktop:
 	Select Apply and Restart."
 endef
 
+build-wheel:
+	@python setup.py sdist
+
 build-keria: .warn
-	@docker build --platform=linux/amd64,linux/arm64 --no-cache -f images/keria.dockerfile -t weboftrust/keria:$(VERSION) .
+	@docker build \
+		--build-arg KERI_AGENT_CORS=false \
+		--platform=linux/amd64,linux/arm64 \
+		--no-cache \
+		-f images/keria.dockerfile \
+		-t $(LATEST_TAG) \
+		-t $(VERSION_TAG) \
+		.
 
 publish-keria:
-	@docker push weboftrust/keria:$(VERSION)
+	@docker push $(VERSION_TAG) && docker push $(LATEST_TAG)
 
 .warn:
 	@echo -e ${RED}"$$DOCKER_WARNING"${NO_COLOUR}

docs/Makefile

@@ -12,9 +12,22 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile  clean html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo
+
+open:
+	open _build/html/index.html
+

docs/conf.py

@@ -18,7 +18,7 @@
     sphinx_rtd_theme = None
 
 project = 'KERIA'
-copyright = '2023, Phil Feairheller'
+copyright = '2025, Phil Feairheller'
 author = 'Phil Feairheller'
 
 version = release = keria.__version__

docs/keria_app.rst

@@ -7,6 +7,78 @@ keria.app.agenting
 .. automodule:: keria.app.agenting
     :members:
 
+Agency and Agent Configuration
+===================
+
+A KERIA Agency can be configured with either environment variables or a configuration file.
+The configuration file is a JSON file. Both alternatives are shown here.
+
+Environment Variables
+---------------------
+
+.. code-block:: bash
+
+    # Service Endpoint Location URLs creating Endpoint Role Authorizations and Location Scheme records on startup
+    export KERIA_CURLS="https://url1,https://url2"
+    # Introduction URLs resolved on startup (OOBIs)
+    export KERIA_IURLS="https://url3,https://url4"
+    # Data OOBI URLs resolved on startup
+    export KERIA_DURLS="https://url5,https://url6"
+    # how long before an agent can be idle before shutting down; defaults to 1 day
+    export KERIA_RELEASER_TIMEOUT=86400
+
+JSON Configuration File
+-----------------------
+
+To use the JSON configuration file option make sure to mount the JSON file to the directory you specify with the
+`--config-dir` option and name the JSON file the name specified by the `--config-dir` option to the `keria start` command like so.
+
+With the absolute path version the `--config-dir` argument does not have an affect since the
+`--config-file` argument specifies the absolute path to the JSON file.
+
+.. code-block:: bash
+
+    # Relative path version, interpreted relative to directory executing keria binary from.
+    # This means the file "keria.json" must exist in the "scripts/keri/cf" folder
+    keria start \
+        --config-dir scripts \
+        --config-file keria
+
+    # Absolute path version
+    keria start \
+        --config-dir /path/to/config-dir/keria.json \
+        --config-file /path/to/config-dir/keria.json
+
+The JSON file must have an object with the same name that you sent to the `keria start` command via the `--name` argument.
+The default is "keria" which is why the JSON file below shows a sub-object named "keria".
+Make sure to include the "dt" date timestamp field or the configuration will not be loaded.
+
+You can configure the cycle time, or tocks, of the escrower as well as the agent initializer.
+
+You can also configure the CURLs, IURLs, and DURLs of the agent.
+CURLs are Service Endpoint Location URLs creating Endpoint Role Authorizations and Location Scheme records on startup.
+IURLS are Introduction URLs resolved on startup (OOBIs).
+DURLS are Data OOBI URLs resolved on startup usually of things like ACDC credential schemas or ACDC credential CESR streams.
+
+.. code-block:: json
+
+    {
+      "dt": "2025-01-13T16:08:30.123456+00:00",
+      "keria": {
+        "dt": "2025-01-13T16:08:30.123457+00:00",
+        "curls": ["http://127.0.0.1:3902/"]
+      },
+      "iurls": [
+        "http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness",
+        "http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wil&tag=witness",
+        "http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wes&tag=witness"
+      ],
+      "tocks": {
+        "initer": 0.0,
+        "escrower": 1.0
+      }
+    }
+
 keria.app.aiding
 ----------------
 

docs/requirements.txt

@@ -1,3 +1,11 @@
-myst-parser >= 0.16.1
-Sphinx >= 4.3.2
-sphinx-rtd-theme >= 1.2.2
+myst-parser >= 4.0.0
+Sphinx >= 8.1.3
+
+sphinx-rtd-theme==3.0.1
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0

images/keria.dockerfile

@@ -1,8 +1,9 @@
 # Builder stage
-FROM python:3.12-alpine3.19 as builder
+FROM python:3.12.8-alpine3.21 AS builder
 
 # Install compilation dependencies
 RUN apk --no-cache add \
+    curl \
     bash \
     alpine-sdk \
     libffi-dev \
@@ -13,29 +14,32 @@ SHELL ["/bin/bash", "-c"]
 
 # Install Rust for blake3 dependency build
 RUN curl https://sh.rustup.rs -sSf | bash -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
 
 WORKDIR /keria
 
 RUN python -m venv venv
 ENV PATH=/keria/venv/bin:${PATH}
-RUN pip install --upgrade pip
 
-# Copy in Python dependency files
-COPY requirements.txt setup.py ./
+RUN pip install --upgrade pip
 # "src/" dir required for installation of dependencies with setup.py
 RUN mkdir /keria/src
+# Copy in Python dependency files
+COPY requirements.txt setup.py ./
+
 # Install Python dependencies
-RUN . "$HOME/.cargo/env" && \
-    pip install -r requirements.txt
+RUN . "$HOME/.cargo/env"
+RUN pip install -r requirements.txt
 
 # Runtime stage
-FROM python:3.12-alpine3.19
+FROM python:3.12.8-alpine3.21
 
 # Install runtime dependencies
 RUN apk --no-cache add \
     bash \
-    alpine-sdk \
-    libsodium-dev
+    curl \
+    libsodium-dev \
+    gcc
 
 WORKDIR /keria
 

scripts/keri/cf/keria.json

@@ -0,0 +1,16 @@
+{
+  "dt": "2025-01-03T16:08:30.123456+00:00",
+  "keria": {
+    "dt": "2025-01-03T16:08:30.123457+00:00",
+    "curls": ["http://127.0.0.1:3902/"]
+  },
+  "iurls": [
+    "http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness",
+    "http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wil&tag=witness",
+    "http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wes&tag=witness"
+  ],
+  "tocks": {
+    "initer": 0.0,
+    "escrower": 1.0
+  }
+}

setup.py

@@ -24,20 +24,27 @@
 https://caremad.io/posts/2013/07/setup-vs-requirement/
 """
 
-
+from pathlib import Path
 from glob import glob
 from os.path import basename
 from os.path import splitext
 
 from setuptools import find_packages
 from setuptools import setup
 
+this_directory = Path(__file__).parent
+if (this_directory / "README.md").exists():  # If building inside a container, like in the `images/keria.dockerfile`, this file won't exist and fails the build
+    long_description = (this_directory / "README.md").read_text()
+else:
+    long_description = "KERIA: KERI Agent in the cloud."
+
 setup(
     name='keria',
-    version='0.2.0-dev6',  # also change in src/keria/__init__.py
+    version='0.2.0-rc1',  # also change in src/keria/__init__.py
     license='Apache Software License 2.0',
     description='KERIA: KERI Agent in the cloud',
-    long_description="KERIA: KERI Agent in the cloud.",
+    long_description=long_description,
+    long_description_content_type='text/markdown',
     author='Philip S. Feairheller',
     author_email='[email protected]',
     url='https://github.com/WebOfTrust/keria',
@@ -54,7 +61,7 @@
         'Operating System :: Unix',
         'Operating System :: POSIX',
         'Operating System :: Microsoft :: Windows',
-        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.12',
         'Programming Language :: Python :: Implementation :: CPython',
         # uncomment if you test on these interpreters:
         # 'Programming Language :: Python :: Implementation :: PyPy',
@@ -64,37 +71,37 @@
         'Topic :: Utilities',
     ],
     project_urls={
+        'Documentation': 'https://weboftrust.github.io/keridoc',
         'Issue Tracker': 'https://github.com/WebOfTrust/keria/issues',
+        'Source': 'https://github.com/WebOfTrust/keria',
     },
     keywords=[
         "secure attribution",
         "authentic data",
         "discovery",
-        "resolver",
-        # eg: 'keyword1', 'keyword2', 'keyword3',
+        "resolver"
     ],
     python_requires='>=3.12.2',
     install_requires=[
-        'hio>=0.6.14',
-        'keri==1.2.0.dev13',
-        'mnemonic>=0.21',
-        'multicommand>=1.0.0',
-        'falcon>=3.1.3',
-        'http_sfv>=0.9.8',
-        'dataclasses_json>=0.5.7',
-        'apispec>=6.6.0',
+        'hio==0.6.14',
+        'keri==1.2.2',
+        'mnemonic==0.21',
+        'multicommand==1.0.0',
+        'falcon==4.0.2',
+        'http_sfv==0.9.9',
+        'dataclasses_json==0.6.7',
+        'apispec==6.8.1',
     ],
     extras_require={
-        # eg:
-        #   'rst': ['docutils>=0.11'],
-        #   ':python_version=="2.6"': ['argparse'],
+        'test': ['pytest', 'coverage'],
+        'docs': ['sphinx', 'sphinx-rtd-theme']
     },
     tests_require=[
-        'coverage>=5.5',
-        'pytest>=6.2.4',
-        'requests==2.32.3'
+        'coverage>=7.6.10',
+        'pytest>=8.3.4',
     ],
     setup_requires=[
+        'setuptools==75.8.0'
     ],
     entry_points={
         'console_scripts': [

src/keria/__init__.py

@@ -3,5 +3,5 @@
 main package
 """
 
-__version__ = '0.2.0-dev6'  # also change in setup.py
+__version__ = '0.2.0-rc1'  # also change in setup.py
 

src/keria/app/agenting.py

@@ -1206,7 +1206,7 @@ def on_get(req, rep):
         pre = req.params.get("pre")
         preb = pre.encode("utf-8")
         events = []
-        for fn, dig in agent.hby.db.getFelItemPreIter(preb, fn=0):
+        for _, fn, dig in agent.hby.db.getFelItemPreIter(preb, fn=0):
             if not (raw := agent.hby.db.cloneEvtMsg(pre=preb, fn=fn, dig=dig)):
                 raise falcon.HTTPInternalServerError(f"Missing event for dig={dig}.")