HTTP Storage

HTTP Storage는 S3나 WebDAV 인터페이스를 제공하지 않는 저장소를 Office에 연결하기 위한 어댑터입니다. 스토리지 서비스가 HTTP Storage Provider를 구현하면 Office가 서명된 HTTP 요청으로 문서를 읽고 저장합니다.

Provider 실행하기

공개 예제 저장소는 Node.js, Spring Boot, FastAPI로 구현한 전체 서버와 샘플 문서를 제공합니다. 각 예제는 Provider의 로컬 디렉터리를 저장소로 사용하며, 모든 프로토콜 작업을 기본으로 지원합니다.

Node.js를 준비하고 다음 명령을 실행합니다. Office가 사용하는 포트 8080과 겹치지 않도록 Provider는 9090에서 실행합니다.

git clone https://github.com/thinkfree/http-storage-provider.git
cd http-storage-provider
npm install
npm run init
TFO_STORAGE_HOST=0.0.0.0 TFO_STORAGE_PORT=9090 npm start

npm run init은 로컬 설정을 만들고 어댑터 이름 local-directory와 생성한 요청 서명 시크릿을 표시합니다. 이 두 값을 관리자 페이지에서 사용합니다. 시크릿은 Office와 Provider에 같은 값을 설정하며, 소스나 로그에 남기지 않습니다.

위 명령은 다른 컨테이너의 Office가 연결할 수 있도록 네트워크 인터페이스에 바인딩합니다. Provider base URL에는 Office에서 접근할 수 있는 서버 IP 또는 DNS 이름과 포트 9090을 사용합니다. Office 컨테이너 안의 127.0.0.1은 그 컨테이너 자체를 가리키므로 호스트에서 실행한 Provider 주소로 사용할 수 없습니다. 신뢰할 수 있는 네트워크 밖에서는 HTTPS로 제공합니다.

별도 터미널에서 같은 디렉터리의 다음 명령을 실행합니다.

TFO_STORAGE_PORT=9090 npm run smoke

Signed listing succeeded와 샘플 파일명이 표시되면 Provider가 서명된 목록 요청에 정상 응답한 것입니다.

다른 프로그래밍 언어의 Provider 예제

Git 저장소에는 Node.js 예제 외에도 Java의 Spring Boot와 Python의 FastAPI로 구현한 Provider 예제가 있습니다. 사용할 프로그래밍 언어에 맞는 예제를 선택하고 각 가이드에서 실행·설정 방법을 확인합니다.

구현	실행 위치와 명령	실행 가이드 · 계약 테스트
Node.js	저장소 루트에서 위 명령 실행	가이드 · `test/app.test.mjs`, `npm test`
Spring Boot	`examples/java`에서 `./run.sh`	가이드 · `HttpStorageProviderApplicationTest.java`, `mvn test`
FastAPI	`examples/python`에서 `./run.sh`	가이드 · `test_app.py`, `.venv/bin/python -m unittest -v`

Spring Boot는 Java·Maven·OpenSSL, FastAPI는 Python과 venv·pip가 필요합니다. 두 예제의 기본 포트는 8080입니다. 첫 실행이 만든 설정 파일에서 포트와 바인딩 주소를 바꾼 뒤 다시 실행합니다. Java는 .env.java의 TFO_STORAGE_PORT·TFO_STORAGE_HOST, Python은 .provider-config.json의 port·host를 사용합니다.

Office에 HTTP Storage 어댑터 등록하기

Office 관리자 페이지에 로그인합니다.
외부연동(External linkage)에서 어댑터 추가(Add Adapter)를 누르고 유형으로 HTTP Storage를 선택합니다.

다음 값을 입력합니다. 아래 예시는 Provider 서버의 주소를 storage.example.com, 포트를 9090으로 사용합니다. storage.example.com은 예시 도메인이므로 Office에서 접근할 수 있는 실제 서버 IP나 도메인으로 바꿉니다.

항목	입력값
이름(Name)	Provider에 설정한 어댑터 이름. Node.js 예제는 `local-directory`
Provider Base URL(Provider base URL)	`http://storage.example.com:9090`. `/tfo-storage/v1`과 문서 경로는 붙이지 않음
요청 서명 시크릿(Request signing secret)	`npm run init`이 생성한 값. Provider에 설정된 시크릿과 같은 값을 입력

연결 테스트(Test connection)를 실행합니다. 아래와 같이 연결과 파일 목록 조회가 성공했다는 메시지가 표시되면 등록(Register)을 누릅니다. 어댑터 목록에 local-directory가 실행 중(Running)으로 표시되는지 확인합니다.

다음은 Node.js 예제의 값을 입력하고 연결 테스트를 완료한 화면입니다. 요청 서명 시크릿은 가려져 있습니다.

Node.js 예제의 local-directory와 Provider 주소를 입력하고 연결 테스트에 성공한 영어 HTTP Storage 등록 화면

등록한 어댑터의 파일 찾아보기(Browse files)를 열면 Provider의 문서 목록을 확인할 수 있습니다. Node.js 예제의 samples 폴더에는 sample.docx, sample.xlsx, sample.pptx가 있습니다.

연결 테스트는 Provider 루트의 list를 호출합니다. Provider가 목록 기능을 구현하지 않았다면 정확한 LIST_NOT_SUPPORTED 응답을 받은 경우에만 파일 탐색을 사용할 수 없다는 안내를 확인하고 등록할 수 있습니다. 인증 실패나 다른 연결 오류는 먼저 해결합니다.

요청 서명 시크릿

요청 서명 시크릿은 Office가 요청에 서명하고 Provider가 이를 검증할 때 사용하는 공유 비밀값입니다. Office와 Provider에 같은 값을 설정해야 합니다. Provider는 서명과 실제 요청 내용을 검증해 요청의 위·변조 여부를 확인합니다.

어댑터 이름과 요청 서명 시크릿은 등록 후 변경할 수 없습니다. 다른 값으로 연결하려면 Provider 설정과 값을 맞춰 새 어댑터를 등록합니다.

문서 URL 만들기

Office URL에는 등록한 어댑터 이름과 Provider 저장소에 상대적인 문서 경로를 넣습니다. Node.js 예제의 storage/samples/sample.docx를 열려면 다음 주소를 사용합니다. Office의 주소나 포트를 바꿨다면 http://localhost:8080을 해당 주소로 바꿉니다.

항목	값
Office 주소	`http://localhost:8080`
Name(이름)	`local-directory`
Provider의 저장소 루트	예제 저장소의 `storage/`
Provider에 있는 파일	`storage/samples/sample.docx`
URL에 넣을 문서 경로	`samples/sample.docx`

Office 주소 뒤에 /cloud-office/api/, 어댑터 이름, 저장소 루트 아래 상대 경로와 /open을 붙입니다.

http://localhost:8080/cloud-office/api/local-directory/samples/sample.docx/open?app=WORD_EDITOR&user_id=test-user&docId=httpsample001

storage/는 Provider의 로컬 루트이므로 URL에 넣지 않습니다. 관리자 화면에 입력한 Provider base URL도 Office URL에 포함하지 않습니다. Provider 주소는 Office가 아래 프로토콜 요청을 보낼 때 사용합니다. 경로에 공백이나 한글이 있으면 각 경로 세그먼트를 URL 인코딩합니다. user_id는 사용자 식별자, docId는 문서를 구분하는 고유한 영문·숫자 값으로 지정합니다. 파일 종류별 app과 전체 옵션은 문서 URL 생성을 참고합니다.

Office가 문서를 열 때 Provider에 보내는 요청은 별도의 프로토콜 URL을 사용합니다.

Provider base URL: https://storage.example.com
Document path:     samples/sample.docx

GET https://storage.example.com/tfo-storage/v1/samples/sample.docx/info
GET https://storage.example.com/tfo-storage/v1/samples/sample.docx/get

Provider 직접 구현하기

Provider를 구현하려면 Office에서 문서를 열고 편집·저장한 뒤 닫는 문서 수명 주기와 아래 작업의 역할을 이해해야 합니다. 문서를 열 때는 info로 정보를 조회하고 get으로 내용을 내려받으며, 편집 결과를 저장소에 반영할 때는 put을 사용합니다. 잠금 기능을 제공한다면 lock과 unlock으로 편집 중인 문서의 잠금과 해제를 처리합니다.

예제를 기반으로 구현할 때는 파일시스템을 읽고 쓰는 부분을 사용할 저장소의 API로 바꿉니다. 요청 인증과 경로 검증은 유지합니다. 전체 Request·Response 규격은 HTTP Storage Protocol에서 확인합니다.

작업	역할	구현 범위
`info`, `get`	문서 정보 조회와 다운로드	문서를 열기 위해 필수
`put`	편집한 전체 문서 저장	저장을 제공할 때 구현
`list`	디렉터리의 바로 아래 항목 조회	파일 탐색을 제공할 때 구현
`lock`, `unlock`	문서 잠금과 해제	둘 다 구현하거나 둘 다 미지원으로 선언
`mkdir`, `rename`, `delete`	디렉터리 생성, 이름 변경, 삭제	제공할 기능만 구현

처리 순서는 다음과 같습니다.

요청 메서드·경로·본문 형식과 크기를 검사합니다. 업로드는 임시 보관하면서 실제 길이와 SHA-256을 계산합니다.
JWT 서명과 유효 기간, 어댑터 이름, 실제 메서드·경로·본문 정보가 일치하는지 검증하고 재사용된 요청 ID를 거부합니다.
인증된 요청의 문서 접근 권한을 확인한 뒤 저장소 작업을 수행합니다. 선택적 작업을 지원하지 않으면 해당 작업의 정확한 501 응답을 반환합니다.
info·list·get·put 응답은 실제 바이트 길이를 Content-Length로 보냅니다. 저장은 본문 검증이 끝난 뒤 대상 파일을 교체하고, 저장된 문서의 docId 하나만 포함하는 JSON 객체를 반환합니다. 형식과 ID 유지 규칙은 PUT 응답을 참고합니다.

info·list·put의 응답 JSON은 각각 최대 5 MiB, 문서는 300 MiB입니다. 이 JSON 응답과 get 응답은 chunked 전송이나 압축을 사용하지 않습니다. 서명 검증, 응답 형식과 크기 제한, 기능 미지원 응답에 정확한 규칙이 있습니다.

put을 지원하지 않으면 저장은 실패합니다. 잠금을 지원하지 않는 경우 Office는 정확한 lock·unlock 미지원 응답을 성공으로 처리하지만 실제 잠금은 생기지 않습니다. 동시 편집 시 마지막 저장으로 덮어쓸지, 충돌을 거부할지 저장소 정책을 정하고 확인합니다.

연결 확인하기

예제의 계약 테스트를 실행해 잘못된 서명, 재사용된 JWT, 잘못된 경로와 크기 초과 요청을 거부하는지 확인합니다.
샘플 문서를 열고 편집·저장·다시 열기까지 확인합니다. 구현한 목록·잠금·생성·이름 변경·삭제도 테스트용 문서로 확인합니다.
선택적 작업을 생략했다면 인증 후 정확한 미지원 응답을 반환하는지, 실제 저장소 오류와 구분되는지 확인합니다.

세부 오류 코드는 프로토콜 오류 응답, 운영 환경의 접근 제어·재전송 방지·파일 처리 기준은 Provider 운영 가이드를 참고합니다.

Provider 실행하기​

다른 프로그래밍 언어의 Provider 예제​

Office에 HTTP Storage 어댑터 등록하기​

문서 URL 만들기​

Provider 직접 구현하기​

연결 확인하기​