1

1

.readthedocs.yaml

@@ -2,6 +2,11 @@ version: 2
 formats: []
 sphinx:
   configuration: conf.py
+  fail_on_warning: false
 python:
   install:
-    - requirements: requirements/docs.txt
+    - requirements: requirements/docs.txt
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"

admin/adv_vhost.rst

@@ -278,6 +278,85 @@ Facade 가상호스트
 
 
 
+.. _adv-vhost-sharevhost:
+
+Share 가상호스트
+====================================
+
+가상호스트를 구성하는 3요소는 다음과 같다.
+
+-  설정
+-  캐싱객체
+-  원본
+
+
+이는 가상호스트 안에 격리되어 있으며 상호 공유되지 않는다.
+
+.. figure:: img/adv_vhost_share1.png
+   :align: center
+
+
+STON은 ``share`` 가상호스트라는 개념으로 캐싱객체를 공유하는 기능을 제공한다.
+
+.. figure:: img/adv_vhost_share2.png
+   :align: center
+
+
+``share`` 로 지정된 가상호스트는 자신의 캐싱객체 대신 공유영역에 있는 캐싱객체를 사용하여 상호 공유가 가능하다.
+예를 들어 ``foo.com`` 가상호스트에서 캐싱한 객체를 ``bar.com`` 에서 공유하고 싶다면 다음 순서를 따른다.
+
+1.  ``foo.com`` 을 ``share`` 가상호스트로 만든다. ::
+
+         # vhosts.xml - <Vhosts>
+
+         <Vhost Name="example.com" Status="share">
+            ...
+         </Vhost>
+
+
+2.  ``bar.com`` 을 ``share`` 가상호스트로 만들며 ``foo.com`` 을 참조하도록 한다. ::
+
+         # vhosts.xml - <Vhosts>
+
+         <Vhost Name="bar.com" Status="share:foo.com">
+            ...
+         </Vhost>
+
+
+
+위와 같이 구성하면 ``foo.com`` 과 ``bar.com`` 은 같은 URL에 대해서는 캐싱 객체를 공유한다.
+다시 말해 ``foo.com`` 에 의해 캐싱된 객체는 ``bar.com`` 으로 접근해도 재캐싱하지 않고 ``TCP_HIT`` 로 서비스 된다.
+``bar.com`` 에 의해 먼저 캐싱된 객체도 동일하게 동작한다.
+
+``share`` 모드에는 가상호스트 이름이 캐싱키로 붙는다. 
+따라서 아래와 같이 선언만 하는 것으로는 아무 것도 공유되지 않는다. ::
+
+   <Vhost Name="foo.com" Status="share"> ... </Vhost>
+   <Vhost Name="bar.com" Status="share"> ... </Vhost>
+   <Vhost Name="que.com" Status="share"> ... </Vhost>
+
+
+상호 캐싱객체를 공유하려면 캐싱키에 사용될 적절한 공유이름을 지정해주어야 한다. ::
+
+   <Vhost Name="foo.com" Status="share:temp"> ... </Vhost>
+   <Vhost Name="bar.com" Status="share:temp"> ... </Vhost>
+   <Vhost Name="que.com" Status="share:temp"> ... </Vhost>
+   <Vhost Name="football.com" Status="share:sports"> ... </Vhost>
+   <Vhost Name="soccer.com" Status="share:sports"> ... </Vhost>
+
+
+공유 그룹 개수에 제약은 없으며, ``share`` 가상호스트는 실시간으로 적용/해제가 가능하다.
+
+
+.. warning::
+
+   ``share`` 가상호스트는 객체만 공유할 뿐 설정/원본을 독립적으로 유지하기 때문에 관리가 매우 어렵다.
+
+   1.  무결성이 보장되지 않는다. 멀티 가상호스트로 동시에 유입된 공유객체는 각자 다른 설정과 다른 원본으로부터 분할 캐싱된다.
+   2.  캐싱개수가 많아져 패턴 Purge 등 객체 관리기능의 성능이 저하된다.
+   3.  객체 유입과 서비스 경로가 명확하지 않아 서비스 추적이 어렵다.
+
+
 
 고급 기능 ``powered by M2``
 ====================================

admin/filesystem.rst

@@ -8,11 +8,11 @@ STON은 `FUSE <http://fuse.sourceforge.net/>`_ 를 기반으로 Linux VFS(Virtua
 Mount된 경로의 모든 파일은 접근되는 순간 Caching되지만 다른 프로세스는 이 사실을 알지 못한다.
 **Caching기능이 탑재된 ReadOnly 디스크** 로 이해해도 좋다.
 
+다음 그림은 `Fuse <http://upload.wikimedia.org/wikipedia/commons/0/08/FUSE_structure.svg>`_ 구조이다.
+
 .. figure:: img/conf_fs1.png
    :align: center
 
-   `Fuse <http://upload.wikimedia.org/wikipedia/commons/0/08/FUSE_structure.svg>`_ 구조
-
 구조상 File I/O 함수 호출을 Linux Kernel이 STON에게 직접 전달하는 과정에 어떠한 요소(물리적 파일 I/O 또는 Socket통신 등)도 개입하지 않는다.
 이런 구조는 아주 높은 성능을 가능케 한다.
 STON의 메모리 Caching을 통해 물리적 디스크 접근보다 뛰어난 성능을 기대할 수 있다.

admin/releasenote.rst

@@ -6,6 +6,19 @@ Appendix E: 릴리스 노트
 v2.9.x
 ====================================
 
+.. _release-cdn-2-9-1:
+
+2.9.1 (2023.11.02)
+----------------------------
+
+-  :ref:`adv-vhost-sharevhost` 기능 추가
+-  ``308 Permanent Redirect`` 응답코드 지원
+-  ``Shared`` 모드로 :ref:`api-conf-reload` 동작시 삭제된 가상호스트가 재배포되던 문제 수정
+-  캐싱 디스크 삭제 동작시점을 여유공간의 20% 이하로 변경
+-  캐싱 디스크를 가용할 수 없는 상황에서 ``Content-Length`` 가 없는 콘텐츠를 캐싱할 때 간헐적으로 비정상 종료 되는 문제 수정
+
+
+
 .. _release-cdn-2-9-0:
 
 2.9.0 (2023.08.11)

index.rst

@@ -9,7 +9,7 @@ STON Edge Server 완벽 가이드
 
 
 :저자: STON 개발팀
-:최신버전: v2.9.0
+:최신버전: v2.9.1
 
 
 1부. STON 기본: 설정 배우기

requirements/docs.txt

@@ -1,4 +1,143 @@
-# Packages required to build docs, independent of application dependencies
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --output-file=requirements/docs.txt requirements/docs.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.13.1
+    # via
+    #   sphinx
+    #   sphinx-intl
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.3.1
+    # via requests
+click==8.1.7
+    # via sphinx-intl
+colorama==0.4.6
+    # via sphinx-autobuild
+docutils==0.18.1
+    # via
+    #   myst-parser
+    #   sphinx
+    #   sphinx-prompt
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.3
+    # via jinja2
+mdit-py-plugins==0.4.0
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==2.0.0
+    # via -r requirements/docs.in
+packaging==23.2
+    # via sphinx
+pbr==5.11.1
+    # via sphinxcontrib-video
+pygments==2.16.1
+    # via
+    #   sphinx
+    #   sphinx-prompt
+    #   sphinx-tabs
+pyyaml==6.0.1
+    # via myst-parser
+readthedocs-sphinx-search==0.3.1
+    # via -r requirements/docs.in
+requests==2.31.0
+    # via sphinx
+six==1.16.0
+    # via
+    #   livereload
+    #   sphinxcontrib-httpdomain
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.2.6
+    # via
+    #   -r requirements/docs.in
+    #   myst-parser
+    #   sphinx-autobuild
+    #   sphinx-copybutton
+    #   sphinx-design
+    #   sphinx-hoverxref
+    #   sphinx-intl
+    #   sphinx-notfound-page
+    #   sphinx-prompt
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-httpdomain
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+    #   sphinxemoji
+    #   sphinxext-opengraph
+sphinx-autobuild==2021.3.14
+    # via -r requirements/docs.in
+sphinx-copybutton==0.5.2
+    # via -r requirements/docs.in
+sphinx-design==0.5.0
+    # via -r requirements/docs.in
+sphinx-hoverxref==1.3.0
+    # via -r requirements/docs.in
+sphinx-intl==2.1.0
+    # via -r requirements/docs.in
+sphinx-multiproject==1.0.0rc1
+    # via -r requirements/docs.in
+sphinx-notfound-page==1.0.0
+    # via -r requirements/docs.in
+sphinx-prompt==1.8.0
+    # via -r requirements/docs.in
+sphinx-rtd-theme==2.0.0rc2
+    # via -r requirements/docs.in
+sphinx-tabs==3.4.4
+    # via -r requirements/docs.in
+sphinxcontrib-applehelp==1.0.7
+    # via sphinx
+sphinxcontrib-devhelp==1.0.5
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.4
+    # via sphinx
+sphinxcontrib-httpdomain==1.8.1
+    # via -r requirements/docs.in
+sphinxcontrib-jquery==4.1
+    # via
+    #   sphinx-hoverxref
+    #   sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.6
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.9
+    # via sphinx
+sphinxcontrib-video @ git+https://github.com/readthedocs/sphinxcontrib-video/
+    # via -r requirements/docs.in
+sphinxemoji==0.2.0
+    # via -r requirements/docs.in
+sphinxext-opengraph==0.9.0
+    # via -r requirements/docs.in
+tornado==6.3.3
+    # via livereload
+urllib3==2.0.7
+    # via requests
 
-# Docs
-docutils<0.18
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools